高度な設定 - 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 アナリティクスにデータが送られます。自動測定機能を使って複数のトラッカーでデータを送りたい場合は、そうした機能を手動で行う必要があります。

ご参考までに、スクリーンの自動測定では GAITrackedViewControllertracker プロパティで指定されたトラッカーが使われます。また、捕捉されなかった例外の測定では、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 からの有用なメッセージ(errorwarninginfoverbose)を冗長モード(詳細レベル)で処理するには 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]];
}