本文件會概略介紹 iOS 專用的 Google Analytics (分析) SDK v3 部分進階設定。
總覽
iOS 版 Google Analytics (分析) SDK 提供
GAITracker
類別,可用於設定資料並傳送至 Google Analytics (分析),以及
GAI
單例模式,用來連結至導入設定的全域設定值。
初始化
如要評估任何資料,您必須先透過 GoogleAnalytics
單例模式初始化至少一個追蹤器,方法是提供追蹤器的名稱和 Google Analytics (分析) 資源 ID:
// 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]];
Measurement Protocol Ampersand 語法
您也可針對單次命中設定值,方法是在 Builder
上設定值;針對所有後續命中值,則可使用 Measurement Protocol 與語法在追蹤程式物件上設定該值:
// 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]];
如需可用 Measurement Protocol 參數的完整清單,請參閱 Measurement Protocol 參數參考資料。
將值套用至多次命中
系統會保留直接在追蹤程式上設定的任何值,並套用至多個命中,如以下範例所示:
// 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 (分析)。如果您正在使用這些功能,並希望使用其他追蹤器傳送資料,則必須手動進行。
為方便您參考,自動螢幕測量功能會使用指定 GAITrackedViewController
的 tracker
屬性中指定的追蹤器。未偵測到的例外狀況測量會使用 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 (分析) 檔案或設定新的用戶端 ID。
方法 1:刪除 Google Analytics (分析) 檔案
如果應用程式未明確設定使用者的用戶端 ID,您可以刪除用來儲存用戶端 ID 的 Google Analytics (分析) 檔案,強制產生新的用戶端 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:設定新的用戶端 ID
您可以產生並設定新的專屬用戶端 ID。所有後續的命中都會使用新的用戶端 ID,先前的資料也不會與新的用戶端 ID 建立關聯。
執行下列程式碼,產生並設定新用戶端 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 資訊去識別化。
以下範例說明如何enable對追蹤程式的 IP 功能去識別化:
[tracker set:kGAIAnonymizeIp value:@"1"];
您可以隨時設定將 IP 功能去識別化,
測試和偵錯
iOS 版 Google Analytics (分析) SDK 提供方便您測試和偵錯的工具。
模擬測試
SDK 提供 dryRun
旗標,設定後可防止任何資料傳送至 Google Analytics (分析)。每次測試或偵錯導入時,都應設定 dryRun
標記,但不希望測試資料顯示在 Google Analytics (分析) 報表中。
如要設定模擬測試標記,請按照下列步驟操作:
[[GAI sharedInstance] setDryRun:YES];
Logger
我們提供 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]]; }