iOS 向け Google アナリティクス SDK - v3 への移行

このガイドでは、iOS 向け Google アナリティクス SDK をバージョン 3(v3)にアップグレードする方法を説明します。

概要: v3 での新機能

v3 の API は、ネイティブ プラットフォームとウェブ プラットフォームでの一貫性が向上するようリファクタリングされています。v2 をご利用の方は、次の変更点にご注意ください。

  • ヒットを送るメソッドは「send:(NSDictionary *)params」1 つになりました。
  • クライアント サイドの自動セッション管理機能は削除されました。代わりに、管理画面でセッション タイムアウトを設定できるようになりました。詳細
  • デバッグモードがロガー(Logger)に置き換えられました。
  • New: ディスパッチしたデータをレポートに表示させないための dryRun フラグが追加されました。
  • New: iOS 向け SDK にローカル通貨のサポートが追加されました。

変更点の一覧については、変更履歴をご覧ください。

準備

v3 へのアップグレードを始めるには、事前に次のものを準備しておく必要があります。

アップグレード パス

まず、現在の実装から v3 にアップグレードするパスを次の中から選択します。

v1.x から v3

Google アナリティクス iOS SDK v1.x をご利用の場合は、v3 のご利用ガイドに従って v3 に切り替えることをおすすめします。

v2.x から v3

v2.x をご利用の場合は、次の手順で v3 にアップグレードしてください。

  1. 便利な send<hit-type> メソッドをすべて新しい send: メソッドに置き換えます。次の例をご覧ください。
    // v2 (Old)
    id<GAITracker> tracker = [[GAI sharedInstance] defaultTracker];
    [tracker sendView:@"HomeScreen"];
    
    // v3
    id<GAITracker> tracker = [[GAI sharedInstance] defaultTracker];
    // Set the screen name on the tracker so that it is used in all hits sent from this screen.
    [tracker set:kGAIScreenName value:@"Home Screen"];
    
    // Send a screenview.
    // [tracker send:[[GAIDictionaryBuilder createAppView]  build]];   // Previous V3 SDK versions.
    [tracker send:[[GAIDictionaryBuilder createScreenView]  build]];   // SDK Version 3.08 and up.
    
  2. クライアント サイドの自動セッション管理機能は削除され、セッション タイムアウトが管理画面で設定できるようになりました(デフォルトは 30 分)。また、sessionControl パラメータを使ってセッションを手動で開始、停止できるようになりました。詳しくは、v3 でのセッション管理に関する説明をご覧ください。

  3. 自動スクリーン トラッキングをご利用の場合は、GAITrackedViewController.trackedViewName の参照を GAITrackedViewController.screenName に置き換える必要があります。次の例をご覧ください。
    // v2 (Old)
    #import "GAITrackedViewController.h"
    
    @implementation AboutViewController
    
    - (void)viewDidAppear:(BOOL)animated {
      [super viewDidAppear:animated];
      self.trackedViewName = @"About Screen";
    }
    
    // ... Rest of ViewController implementation.
    
    // v3
    #import "GAITrackedViewController.h"
    
    @implementation AboutViewController
    
    - (void)viewDidAppear:(BOOL)animated {
      [super viewDidAppear:animated];
      self.screenName = @"About Screen";
    }
    
    // ... Rest of ViewController implementation.
    
  4. デバッグモードのサポートは終了となります。代わりに次のようにロガー(Logger)をご利用ください。
    // v2 (Old)
    [GAI sharedInstance].debug = YES;
    
    // v3
    [[GAI sharedInstance].logger setLogLevel:kGAILogLevelVerbose];
    
  5. GAI.useHttp プロパティは削除されました。デフォルトの HTTPS ではなく HTTP を使ってヒットを送る場合は、次のように個々の GAITrackerkGAIUseSecure パラメータを設定してください。
    // v2 (Old)
    // AppDelegate.m
    
    #import AppDelegate.h
    #import GAI.h
    
    - (BOOL)application:(UIApplication *)application didFinishLaunchingWithOptions:(NSDictionary *)launchOptions {
    
        static NSString const *kGaPropertyId = @"UA-XXXX-Y";
        id tracker = [[GAI sharedInstance] trackerWithTrackingId:kGaPropertyId];
    
        // Send hits using HTTP (default=HTTPS).
        tracker.useHttps = NO;
    
    }
    
    // v3
    // AppDelegate.m
    
    #import AppDelegate.h
    #import GAI.h
    
    - (BOOL)application:(UIApplication *)application didFinishLaunchingWithOptions:(NSDictionary *)launchOptions {
    
        static NSString const *kGaPropertyId = @"UA-XXXX-Y";
        id tracker = [[GAI sharedInstance] trackerWithTrackingId:kGaPropertyId];
    
        // Send hits using HTTP (default=HTTPS).
        [tracker set:kGAIUseSecure value:[@NO stringValue]];
    
    }
    
  6. v3 SDK では、アプリが起動したときに自動的に新しいセッションが始まることはありません。この v2 の機能を残したい場合は、ユーザーがアプリを起動したときに独自のセッション管理機能を実装する必要があります。次の例をご覧ください。
  7. // AppDelegate.m
    
    #import AppDelegate.h
    #import GAI.h
    
    - (BOOL)application:(UIApplication *)application didFinishLaunchingWithOptions:(NSDictionary *)launchOptions {
    
        static NSString const *kGaPropertyId = @"UA-XXXX-Y";
        id tracker = [[GAI sharedInstance] trackerWithTrackingId:kGaPropertyId];
    
        // CAUTION: Setting session control directly on the tracker persists the
        // value across all subsequent hits, until it is manually set to null.
        // This should never be done in normal operation.
        //
        // [tracker set:kGAISessionControl value:@"start"];
    
        // Instead, send a single hit with session control to start the new session.
        [tracker send:[[[GAIDictionaryBuilder createEventWithCategory:@"UX"
                                                               action:@"appstart"
                                                                label:nil
                                                                value:nil] set:@"start" forKey:kGAISessionControl] build]];
    
    
  8. アプリ単位のオプトアウト設定は SDK で保存されなくなったため、アプリの起動時に毎回必ず設定してください(デフォルトでは NO になります)。 詳しくは、アプリ単位のオプトアウト設定の説明をご覧ください。

リファレンス

次のセクションでは、v3 SDK を使ってデータを設定、送信する具体例を示します。

v3 でマップを使ってデータを送信

v3 では、Google アナリティクスのフィールドと値のマップである NSDictionary を引数とする send: メソッド 1 つを使ってデータを送信します。ヒットの構築プロセスを簡略化するため、GAIDictionaryBuilder ユーティリティ クラスが用意されています。次の例をご覧ください。

id<GAITracker> tracker = [[GAI sharedInstance] defaultTracker];
[tracker set:kGAIScreenName value:@"Home Screen"];

// Previous V3 SDK versions.
// [tracker send:[[GAIDictionaryBuilder createAppView] setValue:@"Premium"  // Creates a Map of hit type 'AppView' (screenview) and set any additional fields.
//                                                     forKey:[customDimensionForIndex:1] build]; // Build and return the dictionary to the send method.

// SDK Version 3.08 and up.
[tracker send:[[GAIDictionaryBuilder createScreenView] setValue:@"Premium"  // Creates a Map of hit type 'ScreenView' and set any additional fields.
                                                       forKey:[customDimensionForIndex:1] build]; // Build and return the dictionary to the send method.

対応するヒットタイプ(イベントなど)を構築する際には、GAIDictionaryBuilder クラスを使用できます。

id<GAITracker> tracker = [[GAI sharedInstance] defaultTracker];

[tracker send:[[GAIDictionaryBuilder createEventWithCategory:@"ui_action"     // Event category (required)
                                                      action:@"button_press"  // Event action (required)
                                                       label:@"play"          // Event label
                                                       value:nil] build]];    // Event value

詳しくは、v3 でのデータ送信に関する説明をご確認ください。

v3 でトラッカーにデータを設定

set:value:forKey メソッドを使えば、GAITracker に値を直接設定することもできます。直接設定された値は、その GAITracker で発生する後続のすべてのヒットに適用されます。次の例をご覧ください。

// Values set directly on a tracker apply to all subsequent hits.
[tracker set:kGAIScreenName value:@"Home Screen"];

// This screenview hit will include the screen name "Home Screen".
// [tracker send:[[GAIDictionaryBuilder createAppView] build]];   // Previous V3 SDK versions.
[tracker send:[[GAIDictionaryBuilder createScreenView] build]];   // SDK Version 3.08 and up.

// And so will this event hit.
[tracker send:[[GAIDictionaryBuilder createEventWithCategory:@"ui_action"
                                                      action:@"button_press"
                                                       label:@"play"
                                                       value:nil] build]];

GAITracker に設定した値をクリアするには、そのプロパティに nil を設定します。次の例をご覧ください。

// Clear the previously-set screen name value.
[tracker set:kGAIScreenName
       value:nil];

// Now this event hit will not include a screen name value.
[tracker send:[[GAIDictionaryBuilder createEventWithCategory:@"ui_action"
                                                      action:@"button_press"
                                                       label:@"play"
                                                       value:nil] build]];

詳しくは、v3 でのデータ設定に関する説明を ご覧ください。