このドキュメントでは、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;
匿名 IP
IP 匿名化機能を有効にすると、Google アナリティクスでは IP アドレスを保存する前にアドレスの下位 8 ビットを削除して、SDK から送信された IP 情報を匿名化します。
トラッカーに対して IP 匿名化機能を有効にする方法を次の例に示します。
[tracker set:kGAIAnonymizeIp value:@"1"];
IP 匿名化機能はいつでも設定できます。
テストとデバッグ
iOS 向け Google アナリティクス SDK には、テストとデバッグを容易にするためのツールがあります。
Dry Run フラグ
この SDK に備わっている dryRun
フラグをセットすると、Google アナリティクスにデータが送られなくなります。実装のテストやデバッグを行う際に Google アナリティクスにテストデータを送りたくない場合は、必ず dryRun
フラグを設定してください。
dry run フラグを設定するには、次のように記述します。
[[GAI sharedInstance] setDryRun:YES];
Logger
SDK からの有用なメッセージ(error
、warning
、info
、verbose
)を冗長モード(詳細レベル)で処理するには GAILogger
プロトコルを使用します。
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 アナリティクスの実装を初期化し、1 つのスクリーン ビューを送信するコードです。
2 番目のサンプルコードは、最初のスクリーンがユーザーに表示された時点でスクリーン ビューを測定するコードです。
一般的に実装の初期化は、次の例のようにアプリのデリゲートから行います。
// // 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]]; }