Android v3(レガシー)- 概要

このデベロッパー ガイドでは、モバイルアプリに Google タグ マネージャーを実装する方法について説明します。

はじめに

Google タグ マネージャーを使用すると、デベロッパーは Google タグ マネージャーのインターフェースを使用してモバイルアプリの設定値を変更できます。アプリのバイナリを再ビルドしてアプリ マーケットプレイスに再送信する必要はありません。

これは、将来変更が必要になる可能性のあるアプリケーションの構成値やフラグを管理する場合に便利です。たとえば、次のようなものがあります。

  • さまざまな UI 設定と表示文字列
  • アプリで配信される広告のサイズ、場所、タイプ
  • ゲームの設定

構成値は、ルールを使用して実行時に評価することもできます。これにより、次のような動的な構成が可能になります。

  • 画面サイズを使用して広告バナーのサイズを決定する
  • 言語と地域を使用して UI 要素を構成する

Google タグ マネージャーを使用すると、アプリケーションにトラッキング タグとピクセルを動的に実装することもできます。デベロッパーは、重要なイベントをデータレイヤーにプッシュし、どのトラッキング タグやピクセルを配信するかを後で決めることができます。TagManager は次のタグをサポートしています。

  • Google モバイルアプリ解析
  • カスタム関数呼び出しタグ

始める前に

このスタートガイドを使用する前に、次のものが必要になります。

Google タグ マネージャーを初めて使用する場合は、このガイドを読み進める前に、コンテナ、マクロ、ルールの詳細(ヘルプセンター)を確認することをおすすめします。

スタートガイド

このセクションでは、タグ マネージャーの一般的なワークフローについて説明します。

  1. Google タグ マネージャー SDK をプロジェクトに追加する
  2. コンテナのデフォルト値を設定する
  3. コンテナを開く
  4. コンテナから構成値を取得する
  5. イベントをデータレイヤーに push する
  6. コンテナをプレビューして公開する

1. Google タグ マネージャー SDK をプロジェクトに追加する

Google タグ マネージャー SDK を使用する前に、SDK パッケージを抽出して、プロジェクトのビルドパスにライブラリを追加し、AndroidManifest.xml ファイルに権限を追加する必要があります。

まず、Google タグ マネージャー ライブラリをプロジェクトの /libs フォルダに追加します。

次に、AndroidManifest.xml ファイルを更新して、次の権限を使用します。

<uses-permission android:name="android.permission.ACCESS_NETWORK_STATE" />
<uses-permission android:name="android.permission.INTERNET" />

2. プロジェクトにデフォルトのコンテナ ファイルを追加する

Google タグ マネージャーは、アプリケーションの初回実行時にデフォルトのコンテナを使用します。アプリがネットワーク経由で新しいコンテナを取得できるようになるまで、デフォルトのコンテナが使用されます。

デフォルトのコンテナ バイナリをダウンロードしてアプリケーションに追加する手順は次のとおりです。

  1. Google タグ マネージャーのウェブ インターフェースにログインします。
  2. ダウンロードするコンテナのバージョンを選択します。
  3. [ダウンロード] ボタンをクリックして、コンテナ バイナリを取得します。
  4. バイナリ ファイルを次のパスに追加します。<project-root>/assets/tagmanager/

デフォルトのファイル名はコンテナ ID(例: GTM-1234)です。バイナリ ファイルをダウンロードしたら、ファイル名からバージョン接尾辞を削除して、正しい命名規則に従っていることを確認してください。

バイナリ ファイルの使用をおすすめしますが、コンテナにルールやタグが含まれていない場合は、代わりに JSON ファイルを使用することもできます。このファイルは、Android プロジェクトの新しい /assets/tagmanager フォルダに配置する必要があります。また、命名規則 <Container_ID>.json に従う必要があります。たとえば、コンテナ ID が GTM-1234 の場合は、デフォルトのコンテナ値を /assets/tagmanager/GTM-1234.json に追加する必要があります。

3. コンテナを開く

コンテナから値を取得する前に、アプリケーションでコンテナを開く必要があります。コンテナを開くと、ディスクから読み込まれるか(利用可能な場合)、ネットワークからリクエストされます(必要な場合)。

Android でコンテナを開く最も簡単な方法は、次の例のように ContainerOpener.openContainer(..., Notifier notifier) を使用することです。

import com.google.tagmanager.Container;
import com.google.tagmanager.ContainerOpener;
import com.google.tagmanager.ContainerOpener.OpenType;
import com.google.tagmanager.TagManager;

import android.app.Activity;
import android.os.Bundle;

public class RacingGame {

  // Add your public container ID.
  private static final String CONTAINER_ID = "GTM-YYYY";

  volatile private Container mContainer;

  @Override
  public void onCreate(Bundle savedInstanceState) {
    super.onCreate(savedInstanceState);
    TagManager mTagManager = TagManager.getInstance(this);

    // The container is returned to containerFuture when available.
    ContainerOpener.openContainer(
        mTagManager,                            // TagManager instance.
        CONTAINER_ID,                           // Tag Manager Container ID.
        OpenType.PREFER_NON_DEFAULT,            // Prefer not to get the default container, but stale is OK.
        null,                                   // Time to wait for saved container to load (ms). Default is 2000ms.
        new ContainerOpener.Notifier() {        // Called when container loads.
          @Override
          public void containerAvailable(Container container) {
            // Handle assignment in callback to avoid blocking main thread.
            mContainer = container;
          }
        }
    );
    // Rest of your onCreate code.
  }
}

この例では、ContainerOpener.openContainer(..., Notifier notifier) を使用して、ローカル ストレージから保存済みのコンテナをリクエストします。containerAvailable コールバックで mContainer の割り当てを処理することで、メインスレッドがブロックされないようにします。保存されたコンテナが 12 時間以上経過している場合、この呼び出しは、ネットワーク経由で新しいコンテナを非同期で取得するリクエストもスケジュールします。

このサンプル実装は、ContainerOpener コンビニエンス クラスを使用してコンテナを開き、値を取得する最も簡単な方法を示しています。 より高度な実装オプションについては、高度な設定をご覧ください。

4. コンテナから設定値を取得する

コンテナが開いたら、get<type>Value() メソッドを使用して構成値を取得できます。

// Retrieving a configuration value from a Tag Manager Container.

// Get the configuration value by key.
String title = mContainer.getStringValue("title_string");

存在しないキーを使用してリクエストを行うと、リクエストされたタイプに適したデフォルト値が返されます。

// Empty keys will return a default value depending on the type requested.

// Key does not exist. An empty string is returned.
string subtitle = container.getStringValue("Non-existent-key");
subtitle.equals(""); // Evaluates to true.

5. 値をデータレイヤーにプッシュする

DataLayer は、アプリに関するランタイム情報(タッチイベントやスクリーン ビューなど)を、コンテナ内のタグ マネージャーのマクロやタグで利用できるようにするマップです。

たとえば、スクリーン ビューに関する情報を DataLayer マップにプッシュすると、タグ マネージャーのウェブ インターフェースでタグを設定して、それらのスクリーン ビューに応じてコンバージョン ピクセルとトラッキング コールを呼び出すことができます。これらをアプリにハードコードする必要はありません。

イベントは、push() と DataLayer.mapOf() ヘルパー メソッドを使用して DataLayer に push されます。

//
// MainActivity.java
// Pushing an openScreen event with a screen name into the data layer.
//

import com.google.tagmanager.TagManager;
import com.google.tagmanager.DataLayer;

import android.app.Activity;
import android.os.Bundle;

public MainActivity extends Activity {

  public void onCreate(Bundle savedInstanceState) {
    super.onCreate(savedInstanceState);

  }

  // This screen becomes visible when Activity.onStart() is called.
  public void onStart() {
    super.onStart();

    // The container should have already been opened, otherwise events pushed to
    // the DataLayer will not fire tags in that container.
    DataLayer dataLayer = TagManager.getInstance(this).getDataLayer();
    dataLayer.push(DataLayer.mapOf("event",
                                   "openScreen",      // The event type. This value should be used consistently for similar event types.
                                   "screenName",      // Writes a key "screenName" to the dataLayer map.
                                   "Home Screen")     // Writes a value "Home Screen" for the "screenName" key.
    );
  }
  // Rest of the Activity implementation
}

ウェブ インターフェースで、 equals "openScreen" というルールを作成することで、各スクリーンビューで配信されるタグ(Google アナリティクス タグなど)を作成できるようになりました。これらのタグのいずれかにスクリーン名を渡すには、データレイヤーの「screenName」キーを参照するデータレイヤー マクロを作成します。また、 が「openScreen」に等しく、かつ が「ConfirmationScreen」に等しいというルールを作成することで、特定のスクリーン ビューでのみ配信されるタグ(Google 広告のコンバージョン ピクセルなど)を作成することもできます。

6. コンテナのプレビューと公開

マクロの値は、常に現在公開されているバージョンに対応します。 コンテナの最新バージョンを公開する前に、ドラフト コンテナをプレビューできます。

コンテナをプレビューするには、Google タグ マネージャーのウェブ インターフェースで、プレビューするコンテナのバージョンを選択し、[Preview] を選択することにより、プレビュー URL を生成します。後の手順で使用するために、このプレビュー URL を保存しておきます。

プレビュー URL は、タグ マネージャー管理画面のプレビュー ウィンドウで利用できます
図 1: タグ マネージャーのウェブ インターフェースからプレビュー URL を取得する。

次に、アプリの AndroidManifest.xml ファイルに次のアクティビティを追加します。

<!-- Google Tag Manager Preview Activity -->
<activity
  android:name="com.google.tagmanager.PreviewActivity"
  android:label="@string/app_name"
  android:noHistory="true" >  <!-- Optional, removes the PreviewActivity from activity stack. -->
  <intent-filter>
    <data android:scheme="tagmanager.c.application_package_name" />
    <action android:name="android.intent.action.VIEW" />
    <category android:name="android.intent.category.DEFAULT" />
    <category android:name="android.intent.category.BROWSABLE"/>
  </intent-filter>
</activity>
  

エミュレータまたは実機でリンクを開き、アプリでドラフト コンテナをプレビューします。

ドラフト構成値をアプリケーションで使用できるようにする準備ができたら、コンテナを公開します。

詳細設定

モバイル向け Google タグ マネージャーには、ルールを使用してランタイム条件に基づいて値を選択したり、コンテナを手動で更新したり、コンテナを開くための追加オプションを取得したりできる、高度な設定オプションが多数用意されています。以下のセクションでは、最も一般的な詳細設定について説明します。

コンテナを開くための詳細オプション

Google タグ マネージャー SDK には、コンテナを開くためのメソッドがいくつか用意されており、読み込みプロセスをより細かく制御できます。

TagManager.openContainer()

TagManager.openContainer() は、コンテナを開くための最も低いレベルで最も柔軟な API です。デフォルトのコンテナをすぐに返します。また、保存されたコンテナが存在しない場合や、保存されたコンテナが最新でない(12 時間以上経過している)場合は、ディスクまたはネットワークからコンテナを非同期で読み込みます。

mContainer = tagManager.openContainer(CONTAINER_ID, new Container.Callback() {

  // Called when a refresh is about to begin for the given refresh type.
  @Override
  public void containerRefreshBegin(Container container, RefreshType refreshType) {
    // Notify UI that the Container refresh is beginning.
   }

  // Called when a successful refresh occurred for the given refresh type.
  @Override
  public void containerRefreshSuccess(Container container, RefreshType refreshType]) {
    // Notify UI that Container is ready.
  }

  // Called when a refresh failed for the given refresh type.
  @Override
  public void containerRefreshFailure(Container container,
                                      RefreshType refreshType,
                                      RefreshFailure refreshFailure) {
    // Notify UI that the Container refresh has failed.
  }

読み込みプロセス全体を通じて、TagManager.openContainer() はいくつかのライフサイクル コールバックを発行します。これにより、読み込みリクエストがいつ開始されたか、失敗または成功したかどうかとその理由、コンテナが最終的にディスクまたはネットワークから読み込まれたかどうかをコードで確認できます。

アプリケーションでデフォルト値を使用することが許容されない限り、これらのコールバックを使用して、保存されたコンテナまたはネットワーク コンテナが読み込まれたことを知る必要があります。アプリを初めて実行するときにネットワーク接続がない場合、保存されたコンテナやネットワーク コンテナを読み込むことはできません。

TagManager.openContainer() は、次の enum 値を引数としてこれらのコールバックに渡します。

RefreshType

値説明
Container.Callback.SAVED 更新リクエストが、ローカルに保存されたコンテナを読み込んでいます。
Container.Callback.NETWORK 更新リクエストがネットワーク経由でコンテナを読み込んでいます。

RefreshFailure

値説明
Container.Callback.NO_SAVED_CONTAINER 保存済みのコンテナはありません。
Container.Callback.IO_ERROR I/O エラーにより、コンテナを更新できませんでした。
Container.Callback.NO_NETWORK 利用可能なネットワーク接続がありません。
Container.Callback.NETWORK_ERROR ネットワーク エラーが発生しました。
Container.Callback.SERVER_ERROR サーバーでエラーが発生しました。
Container.Callback.UNKNOWN_ERROR 分類できないエラーが発生しました。

デフォルト以外のコンテナと新しいコンテナを開く方法

ContainerOpener は TagManager.openContainer() をラップし、コンテナを開くための 2 つの便利なメソッド(ContainerOpener.openContainer(..., Notifier notifier) と ContainerOpener.openContainer(..., Long timeoutInMillis))を提供します。

これらの各メソッドは、デフォルト以外のコンテナまたは新しいコンテナをリクエストする列挙型を受け取ります。

OpenType.PREFER_NON_DEFAULT はほとんどのアプリケーションに推奨されます。指定されたタイムアウト期間内に、ディスクまたはネットワークから、最初に使用可能なデフォルト以外のコンテナを返そうとします。このコンテナが 12 時間以上経過している場合でも同様です。古い保存済みコンテナが返された場合は、新しいコンテナの非同期ネットワーク リクエストも行われます。 OpenType.PREFER_NON_DEFAULT を使用する場合、他のコンテナが利用できない場合や、タイムアウト期間を超過した場合は、デフォルトのコンテナが返されます。

OpenType.PREFER_FRESH は、指定されたタイムアウト期間内にディスクまたはネットワークから新しいコンテナを返そうとします。ネットワーク接続が利用できない場合や、タイムアウト期間を超過した場合は、保存されたコンテナが返されます。

UI フラグや表示文字列など、リクエスト時間が長くなるとユーザー エクスペリエンスに顕著な影響を与える可能性がある場所では、OpenType.PREFER_FRESH を使用しないことをおすすめします。Container.refresh() を使用して、ネットワーク コンテナ リクエストを強制的に実行することもできます。

どちらの簡易メソッドも非ブロッキングです。 ContainerOpener.openContainer(..., Long timeoutInMillis) は ContainerOpener.ContainerFuture オブジェクトを返します。このオブジェクトの get メソッドは、読み込みが完了するとすぐに Container を返します(ただし、それまではブロックされます)。ContainerOpener.openContainer(..., Notifier notifier) メソッドは、コンテナが使用可能になったときに呼び出される単一のコールバックを受け取ります。これを使用して、メインスレッドのブロックを防ぐことができます。どちらのメソッドも、デフォルトのタイムアウト期間は 2000 ミリ秒です。

ルールを使用して実行時にマクロを評価する

コンテナは、ルールを使用して実行時に値を評価できます。ルールは、デバイスの言語、プラットフォーム、その他のマクロ値などの条件に基づいて設定できます。たとえば、ルールを使用して、実行時にデバイスの言語に基づいてローカライズされた表示文字列を選択できます。これは、次のルールを使用して構成できます。

ルールは、実行時にデバイスの言語に基づいて表示文字列を選択するために使用されます。言語は es です。このルールでは、事前定義された言語マクロと 2 文字の ISO 639-1 言語コードを使用します。
図 1: スペイン語を使用するように設定されたデバイスでのみ値収集マクロを有効にするルールを追加する。

次に、言語ごとに値コレクション マクロを作成し、このルールを各マクロに追加して、適切な言語コードを挿入します。このコンテナを公開すると、実行時にユーザーのデバイスの言語に応じて、ローカライズされた表示文字列をアプリに表示できるようになります。

デフォルトのコンテナにルールが必要な場合は、デフォルトのコンテナとしてバイナリ コンテナ ファイルを使用する必要があります。

ルールの設定の詳細(ヘルプセンター)

バイナリのデフォルト コンテナ ファイル

ルールが必要なデフォルト コンテナでは、デフォルト コンテナとして JSON ファイルではなくバイナリ コンテナ ファイルを使用する必要があります。バイナリ コンテナは、Google タグ マネージャーのルールを使用して実行時にマクロ値を決定することをサポートしていますが、JSON ファイルはサポートしていません。

バイナリ コンテナ ファイルは、Google タグ マネージャーのウェブ インターフェースからダウンロードできます。このファイルは、プロジェクトの /assets/tagmanager/ フォルダに追加する必要があります。ファイル名は、/assets/tagmanager/GTM-XXXX のパターンに従います。ここで、ファイル名はコンテナ ID を表します。

JSON ファイルとバイナリ コンテナ ファイルの両方が存在する場合、SDK はバイナリ コンテナ ファイルをデフォルトのコンテナとして使用します。

関数呼び出しマクロの使用

関数呼び出しマクロは、アプリ内の指定された関数の戻り値に設定されるマクロです。関数呼び出しマクロを使用すると、実行時の値を Google タグ マネージャーのルールに組み込むことができます。たとえば、デバイスに設定されている言語と通貨に基づいて、実行時にユーザーに表示する価格を決定できます。

関数呼び出しマクロを設定するには:

  1. Google タグ マネージャーのウェブ インターフェースで関数呼び出しマクロを定義します。 引数は、必要に応じて Key-Value ペアとして構成できます。
  2. Container.registerFunctionCallMacroHandler() と Google タグ マネージャーのウェブ インターフェースで設定した関数名を使用して、アプリケーションに FunctionCallMacroHandler を登録し、その getValue() メソッドをオーバーライドします。
    /**
     * Registers a function call macro handler.
     *
     * @param functionName The function name field, as defined in the Google Tag
     *     Manager web interface.
     */
    mContainer.registerFunctionCallMacroHandler(functionName, new FunctionCallMacroHandler() {
    
      /**
       * This code will execute when any custom macro's rule(s) evaluate to true.
       * The code should check the functionName and process accordingly.
       *
       * @param functionName Corresponds to the function name field defined
       *     in the Google Tag Manager web interface.
       * @param parameters An optional map of parameters
       *     as defined in the Google Tag Manager web interface.
       */
      @Override
      public Object getValue(String functionName, Map<String, Object> parameters)) {
    
        if (functionName.equals("myConfiguredFunctionName")) {
          // Process and return the calculated value of this macro accordingly.
          return macro_value
        }
        return null;
      }
    });

関数呼び出しタグの使用

関数呼び出しタグを使用すると、イベントがデータレイヤにプッシュされ、タグルールが true と評価されるたびに、事前登録された関数を実行できます。

関数呼び出しタグを設定する方法は次のとおりです。

  1. Google タグ マネージャーのウェブ インターフェースで関数呼び出しタグを定義します。 引数は、必要に応じて Key-Value ペアとして構成できます。
  2. Container.registerFunctionCallTagHandler() を使用して、アプリケーションに関数呼び出しタグハンドラを登録します。
    /**
     * Register a function call tag handler.
     *
     * @param functionName The function name, which corresponds to the function name field
     *     Google Tag Manager web interface.
     */
    mContainer.registerFunctionCallTagHandler(functionName, new FunctionCallTagHandler() {
    
      /**
       * This method will be called when any custom tag's rule(s) evaluates to true.
       * The code should check the functionName and process accordingly.
       *
       * @param functionName The functionName passed to the functionCallTagHandler.
       * @param parameters An optional map of parameters as defined in the Google
       *     Tag Manager web interface.
       */
      @Override
      public void execute(String functionName, Map<String, Object> parameters) {
        if (functionName.equals("myConfiguredFunctionName")) {
          // Process accordingly.
        }
      }
    });

カスタム更新期間の設定

Google タグ マネージャー SDK は、現在のコンテナの経過時間が 12 時間を超えると、新しいコンテナの取得を試みます。カスタム コンテナの更新期間を設定するには、次の例のように Timer を使用します。

timer.scheduleTask(new TimerTask() {
  @Override
  public void run() {
    mContainer.refresh();
  }
}, delay, <new_period_in milliseconds>);

Logger によるデバッグ

Google タグ マネージャー SDK は、デフォルトでエラーと警告をログに出力します。より詳細なロギングを有効にすると、デバッグに役立ちます。次の例のように、TagManager.setLogger を使用して独自の Logger を実装することで、詳細ログを有効にできます。

TagManager tagManager = TagManager.getInstance(this);
tagManager.setLogger(new Logger() {

  final String TAG = "myGtmLogger";

  // Log output with verbosity level of DEBUG.
  @Override
  public void d(String arg0) {
    Log.d(TAG, arg0);
  }

  // Log exceptions when provided.
  @Override
  public void d(String arg0, Throwable arg1) {
    Log.d(TAG, arg0);
    arg1.printStackTrace();
  }

  // Rest of the unimplemented Logger methods.

});

または、次の例のように、TagManager.getLogger().setLogLevel(LogLevel) を使用して既存の Logger の LogLevel を設定することもできます。

// Change the LogLevel to INFO to enable logging at INFO and higher levels.
TagManager tagManager = TagManager.getInstance(this);
tagManager.getLogger().setLogLevel(LogLevel.INFO);