進階設定 - iOS SDK

本文件概略說明 Google Analytics (分析) iOS 版 v3 的部分進階設定功能。

總覽

Google Analytics SDK for iOS 提供 GAITracker 類別,用於設定資料並將資料傳送至 Google Analytics (分析),以及 GAI 單例模式介面,可做為您實作的全域設定值介面。

初始化

您必須先在追蹤工具提供 Google Analytics (分析) 資源 ID 和 Google Analytics (分析) 資源 ID 時,透過 GoogleAnalytics 單例模式初始化至少一個追蹤器,才能評估任何資料:

// Initialize a tracker using a Google Analytics property ID.
[[GAI sharedInstance] trackerWithTrackingId:@"UA-XXXX-Y"];

這個追蹤器現在可用於設定資料並傳送至 Google Analytics (分析)。

設定及傳送資料

請在追蹤器上設定參數值組合對應,並透過 setsend 方法傳送資料至 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 符號語法

也可使用 Measurement Protocol 連接號設定在 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]];

如需可用 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 (分析) 就會移除 SDK 儲存空間前方 IP 位址的最後八位元,將 IP 傳送的 IP 資訊去識別化。

以下範例說明如何為追蹤器啟用去識別化 IP 功能:

[tracker set:kGAIAnonymizeIp value:@"1"];

您隨時可以設定去識別化 IP 功能。

測試和偵錯

Google Analytics SDK for iOS 提供相關工具,讓您輕鬆測試及偵錯。

模擬測試

SDK 提供 dryRun 旗標,可防止任何資料傳送至 Google Analytics (分析)。每當您測試或偵錯導入作業,但不希望測試資料出現在 Google Analytics (分析) 報表中,就必須設定 dryRun 旗標。

如要設定模擬測試旗標,請按照下列指示操作:

[[GAI sharedInstance] setDryRun:YES];

Logger

提供 GAILogger 通訊協定,以處理以下這些等級的 SDK 實用訊息:errorwarninginfoverbose

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]];
}