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

このガイドでは、Android 向け Google アナリティクス SDK を V3 にアップグレードする方法について説明します。

概要: v3 での新機能

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

• 単一の send(Map<String, String> parameters) メソッドでヒットを送信できるようになりました。
• デバッグモードを Logger に置き換えました。
• EasyTracker が Tracker をサブクラス化し、インターフェースに変更が加えられました。
• 新規: ディスパッチされたデータがレポートに表示されないように、dryRun フラグが追加されました。

変更内容の完全なリストについては、Android の変更履歴をご覧ください。

始める前に

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

• ユニバーサル アナリティクス対応のプロパティとアプリ プロファイル
• Android 向け Google アナリティクス SDK v3

アップグレード パス

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

• EasyTracker: v1.x から v3
• EasyTracker: v2.x から v3
• カスタム実装: v1.x から v3
• カスタム実装: v2.x から v3

EasyTracker: v1.x から v3

EasyTracker v1.x のユーザーは、v3 のスタートガイドに沿って EasyTracker で v3 の使用を開始することをおすすめします。

EasyTracker: v2.x から v3

v2.x EasyTracker ユーザーは、次の手順に沿って v3 へのアップグレードを完了する必要があります。

1. EasyTracker.getInstance() の呼び出しを更新して、Context: を指定します。

   // v2 (Old)
   // EasyTracker.getInstance().activityStart(this);
   

   // v3:
   EasyTracker.getInstance(this).activityStart(this);
   

2. EasyTracker は Tracker をサブクラス化するようになりました。EasyTracker.getTracker() への呼び出しは削除されました。

   // v2 (Old)
   Tracker v2Tracker = EasyTracker.getInstance().getTracker();
   

   // v3
   Tracker v3Tracker = EasyTracker.getInstance(this);
   

3. すべての send<hit-type> コンビニエンス メソッドを新しい send(Map<String, String> parameters) メソッドに置き換えます。

   // v2 (Old)
   Tracker v2EasyTracker = EasyTracker.getInstance().getTracker(this);
   v2EasyTracker.sendView("Home Screen");
   

   // v3
   Tracker v3EasyTracker = EasyTracker.getInstance(this);
   
   // Set the screen name on the tracker so that it is used in all hits sent from this screen.
   v3EasyTracker.set(Fields.SCREEN_NAME, "Home Screen");
   
   // Send a screenview.
   v3EasyTracker.send(MapBuilder
     .createAppView()
     .build()
   );
   

   v3 でのデータ送信の詳細。



4. ga_debug EasyTracker パラメータを ga_logLevel に置き換え、詳細値（verbose、info、warning、error）のいずれかを指定します。

   <!-- res/values/analytics.xml -->
   
   <?xml version="1.0" encoding="utf-8"?>
   <resources>
     <string name="ga_trackingId">UA-XXXX-Y</string>
     <!-- REMOVE: <bool name="ga_debug">true</bool> -->
     <string name="ga_logLevel">verbose</string>
   </resources>
   

   詳しくは、EasyTracker パラメータ リファレンスをご覧ください。



5. GoogleAnalytics.requestAppOptOut() はサポートが終了しています。代わりに GoogleAnalytics.getAppOptOut() を使用してください。

   // v2 (Old)
   GoogleAnalytics.getInstance(this).requestAppOptOut(new AppOptOutCallback() {
      @Override
      public void reportAppOptOut(boolean optOut) {
        if (optOut) {
        ... // Alert the user that they've opted out.
        }
      });
   }
   

   // v3
   boolean optOutPreference = GoogleAnalytics.getInstance(this).getAppOptOut();
   

6. （省略可）実装をテストする際は、テストデータが本番環境レポートに表示されないように、ga_dryRun EasyTracker パラメータを追加し、true に設定します。

<!-- res/values/analytics.xml -->

<?xml version="1.0" encoding="utf-8"?>

<resources>
  <string name="ga_trackingId">UA-XXXX-Y</string>
  <string name="ga_logLevel">verbose</string>

  <!-- Prevent data from appearing in reports. Useful for testing. -->
  <bool name="ga_dryRun">true</bool>

</resources>

カスタム実装: v1.x から v3

EasyTracker を使用していない v1.x ユーザーは、V3 のスタートガイドに従って、必要に応じて高度な構成のデベロッパー ガイドをご覧ください。

カスタム実装: v2.x から v3

EasyTracker を使用していない v2.x ユーザーは、以下の手順に沿って v3 へのアップグレードを完了する必要があります。

1. すべての 'send<hit-type>' コンビニエンス メソッドを新しい send(Map<String, String> parameters) メソッドに置き換えます。

   // v2 (Old)
   Tracker v2Tracker = GoogleAnaytics.getInstance(this).getTracker("UA-XXXX-Y");
   v2Tracker.sendView("Home Screen");
   

   // v3
   Tracker v3Tracker = GoogleAnaytics.getInstance(this).getTracker("UA-XXXX-Y");
   
   // This screen name value will remain set on the tracker and sent with
   // hits until it is set to a new value or to null.
   v3Tracker.set(Fields.SCREEN_NAME, "Home Screen");
   
   v3Tracker.send(MapBuilder
     .createAppView()
     .build()
   );
   

2. GoogleAnalytics.setDebug() の呼び出しを削除し、GoogleAnalytics.getLogger().setLogLevel() に置き換えます。

   // V2 (Old)
   GoogleAnalytics.getInstance(this).setDebug(true);
   

   // V3
   GoogleAnalytics.getInstance(this)
       .getLogger()
       .setLogLevel(LogLevel.VERBOSE);  // VERBOSE | INFO | DEBUG | WARNING
   

   Logger の詳細


3. v3 SDK では、アプリの起動時に新しいセッションが自動的に開始されなくなりました（EasyTracker を使用する場合を除く）。v2 カスタム実装でこの動作を維持するには、ユーザーがアプリを起動したときに独自のセッション制御ロジックを実装する必要があります。

package com.example.app;

import com.google.analytics.tracking.android.GoogleAnalytics;
import com.google.analytics.tracking.android.Tracker;

import android.app.Application;

public class MyApp extends Application {

  private static Tracker mTracker;
  private static final String GA_PROPERTY_ID = "UA-XXXX-Y";

  @Override
  public void onCreate() {
    super.onCreate();
    mTracker = GoogleAnalytics.getInstance(this).getTracker(GA_PROPERTY_ID);

    // 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.
    //
    // mTracker.set(Fields.SESSION_CONTROL, "start");

    // Instead, send a single hit with session control to start the new session.
    mTracker.send(MapBuilder
      .createEvent("UX", "appstart", null, null)
      .set(Fields.SESSION_CONTROL, "start")
      .build()
    );
  }
}

4. （省略可）テスト中に dryRun フラグを設定し、本番環境レポートでテストデータが処理されないようにします。

// When true, dryRun flag prevents data from being processed with reports.
GoogleAnalytics.getInstance(this).setDryRun(true);

Reference

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

v3 でマップを使用してデータを送信する

V3 では、単一の send() メソッドを使用してデータが送信されます。このメソッドは引数として Google アナリティクスのフィールドと値の Map を受け取ります。MapBuilder ユーティリティ クラスは、ヒットを作成するプロセスを簡素化するために提供されています。

// Sending a screenview in v3 using MapBuilder.
Tracker tracker = GoogleAnalytics.getInstance(this).getTracker("UA-XXXX-Y");
tracker.set(Fields.SCREEN_NAME, "Home Screen");

tracker.send(MapBuilder
  .createAppView()                           // Creates a Map of hit type 'AppView' (screenview).
  .set(Fields.customDimension(1), "Premium") // Set any additional fields for this hit.
  .build()                                   // Build and return the Map to the send method.
);

MapBuilder クラスを使用すると、サポートされているヒットタイプ（イベントなど）を構築できます。

// Sending an event in v3 using MapBuilder.createEvent()
tracker.send(MapBuilder
    .createEvent("UX", "touch", "menuButton", null)
    .build()
);

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

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

値は、set() メソッドを使用して Tracker に直接設定することもできます。直接設定された値は、その Tracker からの後続のすべてのヒットに適用されます。

// Values set directly on a tracker apply to all subsequent hits.
tracker.set(Fields.SCREEN_NAME, "Home Screen");

// This screenview hit will include the screen name "Home Screen".
tracker.send(MapBuilder.createAppView().build());

// And so will this event hit.
tracker.send(MapBuilder
  .createEvent("UX", "touch", "menuButton", null)
  .build()
);

Tracker に設定されている値をクリアするには、プロパティを null に設定します。

// Clear the previously-set screen name value.
tracker.set(Fields.SCREEN_NAME, null);

// Now this event hit will not include a screen name value.
tracker.send(MapBuilder
  .createEvent("UX", "touch", "menuButton", null)
  .build()
);

v3 でのデータ設定の詳細