高度な設定 - iOS SDK

このドキュメントでは、iOS v3 向け Google アナリティクス SDK の高度な設定機能の概要を説明します。

概要

iOS 向け Google アナリティクス SDK には、Google アナリティクスにデータを設定して送信するための GAITracker クラスと、実装のグローバル設定値へのインターフェースとして機能する GAI シングルトンが用意されています。

初期化

データの測定を始めるには、GoogleAnalytics シングルトンを使って 1 つ以上のトラッカーを初期化する必要があります。そのためには、トラッカーの名前と Google アナリティクス プロパティ ID を指定します。

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

これで、このトラッカーを使ってデータを設定し、Google アナリティクスに送信できるようになります。

データの設定と送信

Google アナリティクスにデータを送信するには、トラッカーにパラメータと値のペアのマップを設定し、set メソッドと send メソッドを介して送信します。

/*
 * 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 のアンパサンド構文

1 回のヒットに対して値を設定することも、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];

トラッカーに直接設定する値は、複数のヒットで継続して使う値に限定してください。スクリーン名をトラッカーに設定することは、後続のスクリーン ビューやイベントのヒットに同じ値を適用できるため、合理的です。 ただし、トラッカーにヒットタイプなどのフィールドを設定することは、ヒットごとに変わる可能性があるため、おすすめしません。

複数のトラッカーの使用

複数のプロパティにデータを送る場合は、次の例のように 1 つの実装に複数のトラッカーを使用すると便利です。

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.

自動測定機能（スクリーンの自動測定や捕捉されなかった例外の測定など）では、トラッカーを 1 つだけ使って Google アナリティクスにデータが送られます。自動測定機能を使って複数のトラッカーでデータを送りたい場合は、そうした機能を手動で行う必要があります。

参考までに、自動スクリーン測定では特定の GAITrackedViewController の tracker プロパティで指定されたトラッカーが使用されます。キャッチされなかった例外の測定では、GAI インスタンスで指定されたデフォルトのトラッカーが使用されます。

デフォルト トラッカーの使用

Google アナリティクスではデフォルトのトラッカーが維持されます。最初に初期化されたトラッカーがデフォルトのトラッカーになりますが、次の例のように上書きが可能です。

// 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 アナリティクスに送るヒット数を制限することができます。アプリのユーザー数が極めて多い場合や、Google アナリティクスに送るデータが膨大な場合は、サンプリングを行うことで間断なくレポート作成を継続できるようになります。

たとえば、クライアント サイドで抽出率 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 アナリティクスを無効にできます。このフラグはアプリが起動するたびに設定する必要があります。設定するとデフォルトで 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 アナリティクスのクライアント側のデータをリセットまたは削除する必要がある場合は、Google アナリティクスのファイルを削除するか、新しいクライアント ID を設定します。

オプション 1: Google アナリティクスのファイルを削除する

アプリでエンドユーザーのクライアント ID が明示的に設定されていない場合は、クライアント ID の保存に使用する Google アナリティクスのファイルを削除すると、新しいクライアント ID が強制的に生成されます。

次の例では、Google アナリティクスのファイルを削除するための方法を示しています。この方法は、Google アナリティクスを初期化する前に実行する必要があります。

/* 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;
ランダムなクライアント ID を生成するのではなく明示的にクライアント ID を設定する場合は、https://goo.gl/0dlrGx に記載されている有効な UUID（バージョン 4）文字列であることを確認してください。