این سند نمای کلی برخی از ویژگیهای پیکربندی پیشرفته Google Analytics SDK برای iOS نسخه 3 را ارائه میکند.
بررسی اجمالی
Google Analytics SDK برای iOS یک کلاس GAITracker
برای تنظیم و ارسال دادهها به Google Analytics و یک GAI
singleton را ارائه میکند که به عنوان رابطی برای مقادیر پیکربندی جهانی پیادهسازی شما عمل میکند.
مقداردهی اولیه
قبل از اندازهگیری دادهها، باید حداقل یک ردیاب را از طریق GoogleAnalytics
singleton با ارائه یک نام برای ردیاب و شناسه ویژگی Google Analytics مقداردهی کنید:
// Initialize a tracker using a Google Analytics property ID. [[GAI sharedInstance] trackerWithTrackingId:@"UA-XXXX-Y"];
اکنون می توان از این ردیاب برای تنظیم و ارسال داده به Google Analytics استفاده کرد.
تنظیم و ارسال داده ها
داده ها با تنظیم نقشه های جفت پارامتر-مقدار در ردیاب و ارسال آنها از طریق روش های set
و send
به Google Analytics ارسال می شود:
/* * Send a screen view to Google Analytics by setting a map of parameter * values on the tracker and calling send. */ // Retrieve tracker with placeholder property ID. id<GAITracker> tracker = [[GAI sharedInstance] trackerWithTrackingId:@"UA-XXXX-Y"]; NSDictionary *params = [NSDictionary dictionaryWithObjectsAndKeys: @"appview", kGAIHitType, @"Home Screen", kGAIScreenName, nil]; [tracker send:params];
کلاس GAIDictionaryBuilder
فرآیند بازدید از ساختمان را ساده می کند و برای بیشتر موارد استفاده توصیه می شود. در اینجا می توانیم همان نمای صفحه را با خطوط کد کمتری ارسال کنیم:
// Previous V3 SDK versions. // Sending the same screen view hit using [GAIDictionaryBuilder createAppView] // [tracker send:[[[GAIDictionaryBuilder createAppView] set:@"Home Screen" // forKey:kGAIScreenName] build]]; // SDK Version 3.08 and up. // Sending the same screen view hit using [GAIDictionaryBuilder createScreenView] [tracker send:[[[GAIDictionaryBuilder createScreenView] set:@"Home Screen" forKey:kGAIScreenName] build]];
پروتکل اندازه گیری آمپرس و نحو
همچنین میتوان مقادیر را روی یک ضربه، با تنظیم مقدار در Builder
، یا در تمام بازدیدهای بعدی، با تنظیم آن بر روی شی ردیاب، با استفاده از آمپر و نحو پروتکل اندازهگیری تنظیم کرد:
// Sending the same screen view hit using ampersand syntax. // Previous V3 SDK versions. // [tracker send:[[[GAIDictionaryBuilder createAppView] set:@"Home Screen" // forKey:kGAIScreenName] build]]; // SDK Version 3.08 and up. [tracker send:[[[GAIDictionaryBuilder createScreenView] set:@"Home Screen" forKey:kGAIScreenName] build]];
برای لیست کامل پارامترهای پروتکل اندازه گیری موجود، به مرجع پارامتر پروتکل اندازه گیری مراجعه کنید.
اعمال مقادیر برای بازدیدهای متعدد
هر مقداری که مستقیماً روی ردیاب تنظیم شده باشد، باقی می ماند و برای چندین بازدید اعمال می شود، مانند این مثال:
// May return nil if a tracker has not yet been initialized with // a property ID. id<GAITracker> tracker = [[GAI sharedInstance] defaultTracker]; // Set screen name on the tracker to be sent with all hits. [tracker set:kGAIScreenName value:@"Home Screen"]; // Send a screen view for "Home Screen". // [tracker send:[[GAIDictionaryBuilder createAppView] build]]; // Previous V3 SDK versions. [tracker send:[[GAIDictionaryBuilder createScreenView] build]]; // SDK Version 3.08 and up. // This event will also be sent with &cd=Home%20Screen. [tracker send:[[GAIDictionaryBuilder createEventWithCategory:@"UX" action:@"touch" label:@"menuButton" value:nil] build]]; // Clear the screen name field when we're done. [tracker set:kGAIScreenName value:nil];
فقط مقادیری که میخواهید در چندین بازدید باقی بمانند باید مستقیماً روی ردیاب تنظیم شوند. تنظیم یک نام صفحه در یک ردیاب منطقی است، زیرا همان مقدار را می توان برای نمایش های بعدی صفحه نمایش و بازدیدهای رویداد اعمال کرد. با این حال، تنظیم فیلدی مانند نوع ضربه در ردیاب توصیه نمی شود، زیرا احتمالاً با هر ضربه تغییر می کند.
استفاده از ردیاب های متعدد
ردیابهای متعدد ممکن است در یک پیادهسازی استفاده شوند که میتواند برای ارسال دادهها به چندین ویژگی مفید باشد:
id<GAITracker> t1 = [[GAI sharedInstance] trackerWithTrackingId:@"UA-XXXX-1"]; // Trackers may be named. By default, name is set to the property ID. id<GAITracker> t2 = [[GAI sharedInstance] trackerWithName:@"altTracker" trackingId:@"UA-XXXX-2"]; [t1 set:kGAIScreenName value:@"Home Screen"]; [t2 set:kGAIScreenName value:NSStringFromClass([self class])]; // Send a screenview to UA-XXXX-1. // [t1 send:[[GAIDictionaryBuilder createAppView] build]]; // Previous V3 SDK versions. [t1 send:[[GAIDictionaryBuilder createScreenView] build]]; // SDK Version 3.08 and up. // Send a screenview to UA-XXXX-2. // [t2 send:[[GAIDictionaryBuilder createAppView] build]]; // Previous V3 SDK versions. [t2 send:[[GAIDictionaryBuilder createScreenView] build]]; // SDK Version 3.08 and up.
ویژگیهای اندازهگیری خودکار، مانند صفحهنمایش خودکار و اندازهگیری استثنای کشف نشده، تنها از یک ردیاب برای ارسال دادهها به Google Analytics استفاده میکنند. اگر از این ویژگیها استفاده میکنید و میخواهید با استفاده از ردیابهای دیگر داده ارسال کنید، باید این کار را به صورت دستی انجام دهید.
برای مرجع، اندازهگیری خودکار صفحه از ردیاب مشخص شده در ویژگی tracker
یک GAITrackedViewController
معین استفاده میکند. اندازهگیری استثنای کشف نشده از ردیاب پیشفرض مشخصشده در نمونه GAI
شما استفاده میکند.
با استفاده از ردیاب پیش فرض
Google Analytics یک ردیاب پیش فرض دارد. اولین ردیاب اولیه به ردیاب پیش فرض تبدیل می شود اما ممکن است لغو شود:
// t1 becomes the default tracker because it is the first tracker initialized. id<GAITracker> t1 = [[GAI sharedInstance] trackerWithTrackingId:@"UA-XXXX-1"]; id<GAITracker> t2 = [[GAI sharedInstance] trackerWithTrackingId:@"UA-XXXX-2"]; // Returns t1. id<GAITracker> defaultTracker = [[GAI sharedInstance] defaultTracker]; // Hit sent to UA-XXXX-1. // Previous V3 SDK versions. // [defaultTracker send:[[[GAIDictionaryBuilder createAppView] // set:@"Home Screen" forKey:kGAIScreenName] build]]; // SDK Version 3.08 and up. [defaultTracker send:[[[GAIDictionaryBuilder createScreenView] set:@"Home Screen" forKey:kGAIScreenName] build]]; // Override the default tracker. [[GAI sharedInstance] setDefaultTracker:t2]; // Returns t2. defaultTracker = [[GAI sharedInstance] defaultTracker]; // Hit sent to UA-XXXX-2. // Previous V3 SDK versions. // [defaultTracker send:[[[GAIDictionaryBuilder createAppView] // set:NSStringFromClass([self class]) // forKey:kGAIScreenName] build]]; // SDK Version 3.08 and up. [defaultTracker send:[[[GAIDictionaryBuilder createScreenView] set:NSStringFromClass([self class]) forKey:kGAIScreenName] build]];
نمونه برداری
برای محدود کردن تعداد بازدیدهای ارسال شده به Google Analytics، میتوانید نمونهگیری سمت مشتری را فعال کنید. اگر برنامه شما تعداد زیادی کاربر دارد یا حجم زیادی از داده ها را به Google Analytics ارسال می کند، فعال کردن نمونه گیری به اطمینان از گزارش بدون وقفه کمک می کند.
به عنوان مثال، برای اجرای نمونه گیری سمت مشتری با نرخ 50٪، از کد زیر استفاده کنید:
// Assumes a tracker has already been initialized with a property ID, otherwise // getDefaultTracker returns nil. id<GAITracker> tracker = [[GAI sharedInstance] defaultTracker]; // Set a sample rate of 50%. [tracker set:kGAISampleRate value:@"50.0"];
انصراف در سطح برنامه
میتوانید یک پرچم انصراف در سطح برنامه را فعال کنید که Google Analytics را در کل برنامه غیرفعال میکند. توجه داشته باشید که این پرچم باید هر بار که برنامه راه اندازی می شود تنظیم شود و به طور پیش فرض روی NO
خواهد بود.
برای دریافت تنظیمات انصراف در سطح برنامه، از:
// Get the app-level opt out preference. if ([GAI sharedInstance].optOut) { ... // Alert the user they have opted out. }
برای تنظیم انصراف در سطح برنامه، از موارد زیر استفاده کنید:
// Set the app-level opt out preference. [[GAI sharedInstance] setOptOut:YES];
اطلاعات کاربر سمت سرویس گیرنده را حذف کنید
اگر نیاز به بازنشانی یا حذف دادههای سمت سرویس گیرنده Google Analytics برای کاربران نهایی دارید، میتوانید فایلهای Google Analytics را حذف کنید یا یک شناسه مشتری جدید تنظیم کنید.
گزینه 1: فایل های Google Analytics را حذف کنید
اگر برنامه شما به صراحت شناسه مشتری را برای کاربر نهایی تنظیم نکرده است، می توانید با حذف فایل های Google Analytics که برای ذخیره شناسه مشتری استفاده می شود، یک Client ID جدید ایجاد کنید.
از روش مثال زیر می توان برای حذف فایل های Google Analytics استفاده کرد. این روش باید قبل از شروع اولیه Google Analytics اجرا شود:
/* Execute this before [GAI sharedInstance] is initialized. */ static void DeleteGAFiles(void) { NSArray *paths = NSSearchPathForDirectoriesInDomains(NSLibraryDirectory, NSUserDomainMask, YES); NSFileManager *fileManager = [NSFileManager defaultManager]; NSArray *libraryFiles = [fileManager contentsOfDirectoryAtPath:paths.firstObject error:nil]; NSPredicate *predicate = [NSPredicate predicateWithFormat:@"self BEGINSWITH 'googleanalytics'"]; NSArray *matchingFileNames = [libraryFiles filteredArrayUsingPredicate:predicate]; for (NSString *fileName in matchingFileNames) { NSError *error; NSString *filePath = [paths.firstObject stringByAppendingPathComponent:fileName]; if (![fileManager removeItemAtPath:filePath error:&error]) { // Log error. } } }
گزینه 2: یک شناسه مشتری جدید تنظیم کنید
شما می توانید یک شناسه مشتری منحصر به فرد جدید ایجاد و تنظیم کنید. همه بازدیدهای بعدی از شناسه مشتری جدید استفاده می کنند و داده های قبلی با شناسه مشتری جدید مرتبط نمی شوند.
کد زیر را برای ایجاد و تنظیم یک Client ID جدید اجرا کنید:
[GAI sharedInstance].optOut = YES; // This Id should be a valid UUID (version 4) string as described in https://goo.gl/0dlrGx. NSString *newClientID = [NSUUID UUID].UUIDString.lowercaseString; id dispatcher = [[GAI sharedInstance] performSelector:@selector(dispatcher)]; id dataStore = [dispatcher performSelector:@selector(dataStore)]; if ([dataStore respondsToSelector:@selector(setClientId:)]) { [dataStore performSelector:@selector(setClientId:) withObject:newClientID]; } [GAI sharedInstance].optOut = NO;
ناشناس کردن IP
فعال کردن عملکرد ناشناس IP به Google Analytics میگوید که اطلاعات IP ارسال شده توسط SDK را با حذف آخرین اکتت آدرس IP قبل از ذخیرهسازی آن، ناشناس کند.
مثال زیر نشان می دهد که چگونه می توان عملکرد IP ناشناس را برای یک ردیاب فعال کرد :
[tracker set:kGAIAnonymizeIp value:@"1"];
عملکرد ناشناس IP را می توان در هر زمان تنظیم کرد.
تست و اشکال زدایی
Google Analytics SDK برای iOS ابزارهایی را برای آسانتر کردن تست و اشکالزدایی ارائه میکند.
اجرای خشک
SDK یک پرچم dryRun
ارائه می دهد که با تنظیم، از ارسال هرگونه داده به Google Analytics جلوگیری می کند. پرچم dryRun
باید هر زمان که یک پیاده سازی را آزمایش یا اشکال زدایی می کنید تنظیم شود و نمی خواهید داده های آزمایش در گزارش های Google Analytics شما ظاهر شود.
برای تنظیم پرچم خشک اجرا:
[[GAI sharedInstance] setDryRun:YES];
متمرکز ساز
پروتکل GAILogger
برای مدیریت پیامهای مفید از SDK در این سطوح از پرحرفی ارائه شده است: error
، warning
، info
، و verbose
.
SDK یک پیادهسازی استاندارد Logger
را راهاندازی میکند، که بهطور پیشفرض فقط پیامهای هشدار یا خطا را در کنسول ثبت میکند. برای تنظیم پرحرفی Logger
:
// Set the log level to verbose. [[GAI sharedInstance].logger setLogLevel:kGAILogLevelVerbose];
از پیاده سازی های سفارشی Logger
نیز می توان استفاده کرد:
// Provide a custom logger. [[GAI sharedInstance].logger = [[CustomLogger alloc] init];
مثال کامل
مثال زیر کد مورد نیاز برای مقداردهی اولیه پیاده سازی Google Analytics و ارسال یک نمای صفحه نمایش را نشان می دهد.
در مرحله بعد، زمانی که اولین صفحه برای کاربر نمایش داده می شود، نمای صفحه اندازه گیری می شود:
به طور معمول، مقداردهی اولیه یک پیاده سازی را می توان از طریق نماینده برنامه انجام داد، مانند این مثال:
// // AppDelegate.h // #import <UIKit/UIKit.h> #import "GAI.h" @interface AppDelegate : UIResponder <UIApplicationDelegate> @property (strong, nonatomic) UIWindow *window; @property (strong, nonatomic) id<GAITracker> tracker; @end // // AppDelegate.m // #import "AppDelegate.h" /** Google Analytics configuration constants **/ static NSString *const kGaPropertyId = @"UA-XXXX-Y"; // Placeholder property ID. static NSString *const kTrackingPreferenceKey = @"allowTracking"; static BOOL const kGaDryRun = NO; static int const kGaDispatchPeriod = 30; @interface AppDelegate () - (void)initializeGoogleAnalytics; @end @implementation AppDelegate - (void)applicationDidBecomeActive:(UIApplication *)application { [GAI sharedInstance].optOut = ![[NSUserDefaults standardUserDefaults] boolForKey:kTrackingPreferenceKey]; } - (BOOL)application:(UIApplication *)application didFinishLaunchingWithOptions:(NSDictionary *)launchOptions { // Do other work for customization after application launch // then initialize Google Analytics. [self initializeGoogleAnalytics]; return YES; } - (void)initializeGoogleAnalytics { [[GAI sharedInstance] setDispatchInterval:kGaDispatchPeriod]; [[GAI sharedInstance] setDryRun:kGaDryRun]; self.tracker = [[GAI sharedInstance] trackerWithTrackingId:kGaPropertyId]; } // The rest of the app delegate code omitted. @end
سپس، برای اندازه گیری نمای صفحه هنگام نمایش یک نما برای کاربر:
// // MyViewController.m // #import "MyViewController.h" #import "AppDelegate.h" #import "GAI.h" #import "GAIFields.h" #import "GAITracker.h" #import "GAIDictionaryBuilder.h" @implementation MyViewController - (void)viewDidAppear:(BOOL)animated { [super viewDidAppear:animated]; // This screen name value will remain set on the tracker and sent with // hits until it is set to a new value or to nil. [[GAI sharedInstance].defaultTracker set:kGAIScreenName value:@"Home Screen"]; // Send the screen view. // Previous V3 SDK versions. // [[GAI sharedInstance].defaultTracker // send:[[GAIDictionaryBuilder createAppView] build]]; // SDK Version 3.08 and up. [[GAI sharedInstance].defaultTracker send:[[GAIDictionaryBuilder createScreenView] build]]; }