このページは Cloud Translation API によって翻訳されました。

セキュアシグナルアダプターを作成する

セキュアシグナルは、クライアントデバイスが収集して特定の入札者と共有するエンコードデータです。このページでは、Interactive Media Ads（IMA）SDK を使用して安全なシグナルを収集し、Google アドマネージャーに送信する方法について説明します。

始める前に

続行する前に、Android 用 IMA SDK v3.29.0 以降があることを確認してください。

セキュアシグナルアダプターインターフェースを作成する

安全なシグナルを収集して提供するには、インターフェースを実装するクラスを作成します。

package companydomain.path.to.securesignals;
import android.content.Context;
import androidx.annotation.Keep;
import com.google.ads.interactivemedia.v3.api.signals.SecureSignalsAdapter;

/**
 * An example implementation of Secure Signals adapter.
 */
@Keep
public final class MySecureSignalsAdapter implements SecureSignalsAdapter {
  /**
   * Default constructor with no arguments for IMA SDK to instantiate this class.
   */
  public MySecureSignalsAdapter() {
  }
}

アダプタを初期化する

IMA SDK は、アダプタの初期化メソッドを呼び出して、各アダプタを 1 回初期化します。このメソッドを実装して、暗号化の依存関係の開始、キャッシュの設定、すべてのシグナル収集呼び出しで変わらないシグナルの事前計算を行います。

次の例では、アダプタを初期化します。

  ...
  /**
   * Initialize your SDK and any dependencies.
   * IMA SDK calls this function exactly once before signal collection.
   *
   * @param context  The activity context that creates an ads loader.
   * @param callback A callback function to pass initialization results to IMA SDK.
   */
  @Override
  public void initialize(Context context, SecureSignalsInitializeCallback callback) {
    // Initialize your SDK and any dependencies.
    ...

    // Notify IMA SDK of initialization success.
    callback.onSuccess();

    // If signal collection fails, call callback.onFailure();
    // callback.onFailure(new Exception("Signal collection failed."));
  }
  ...

シグナルの収集

広告リクエストの開始前に、IMA SDK はシグナル収集メソッドを非同期で呼び出します。これらのシグナルコレクタメソッドには、暗号化されたシグナルを渡すコールバック関数またはエラーを報告するコールバック関数があります。

次の例では、コールバック関数を使用してセキュアシグナルを収集します。

  ...
  /**
   * Invokes your SDK to collect, encrypt and pass the signal collection results to IMA SDK.
   * IMA SDK calls this function before each ad request.
   *
   * @param context  The activity context that creates an ads loader.
   * @param callback A callback function to pass signal collection results to IMA SDK.
   */
  @Override
  public void collectSignals(Context context, SecureSignalsCollectSignalsCallback callback) {

    try {
      // Collect and encrypt the signals.
      String signals = ...;

      // Pass the encrypted signals to IMA SDK.
      callback.onSuccess(signals);
    } catch (Exception e) {
      // Pass signal collection failures to IMA SDK.
      callback.onFailure(e);
    }
  }
  ...

エラーの報告

アダプタークラスを使用するユーザーと通信するには、シグナルの収集中に発生したすべてのエラーを報告し、シグナルコレクタコールバックに渡します。このプロセスでは、アダプタをアプリケーションに統合する際に発生する問題のトラブルシューティングを行います。

表示されるエラーは次のとおりです。

SDK または依存関係がアプリに見つかりません。
SDK または依存関係に、動作に必要な権限またはユーザーの同意がありません。

アダプタのバージョンを指定する

ワークフローで、アダプターのバージョンを指定してください。IMA SDK は、各広告リクエストにアダプターバージョンを含め、入札リクエストでセキュアシグナルとともに渡します。

入札リクエストでは、アダプターバージョンに基づいて、アダプターがセキュアシグナルの作成に使用する暗号化、エンコード、フォーマットの詳細を特定できます。

次の例では、アダプタのバージョンを指定しています。

  ...
  /**
   * Specifies this adapter's version.
   */
  private static final VersionInfo AdapterVersion = new VersionInfo(1, 0, 1);
  ...
  /**
   * @return The version of this adapter.
   *         IMA SDK calls this function before each ad request.
   */
  @Override
  public VersionInfo getVersion() {
    return AdapterVersion;
  }
  ...

SDK ランタイムバージョンを返す

アダプターは、複数のバージョンの SDK で動作するように設計できます。アダプターが複数のバージョンで動作するようにするには、SDK のランタイムバージョンを返すようにしてください。IMA SDK では、広告リクエストごとにランタイムバージョンとアダプターバージョンが含まれています。

次の例は、SDK ランタイムバージョンをリクエストして返します。

  ...
  /**
   * @return The version of your SDK that this adapter is depending on.
   *         IMA SDK calls this function before each ad request.
   */
  @Override
  public VersionInfo getSDKVersion() {
    // Request the version from your SDK and convert to an IMAVersion.
    int[] mySDKVersion = ...;

    return new VersionInfo(mySDKVersion[0], mySDKVersion[1], mySDKVersion[2]);
  }
  ...

アダプタを Google に登録する

アダプターをシグナル収集用に Google が承認できるようにするには、Android パッケージ名または Google に登録する必要があります。IMA SDK は、Google に登録したアダプターのみを初期化します。

アダプタを検証する

アダプターを検証するには、次のセクションを完了します。

テストアプリケーションを構成する

アダプタを検証する前に、テストアプリケーションを構成します。次の手順を完了します。

IMA SDK の依存関係をモジュールのアプリレベルの Gradle ファイル（app/build.gradle など）に追加します。
```
dependencies {
  implementation 'com.google.ads.interactivemedia.v3:interactivemedia:3.29.0'
}
```
アダプタや SDK などのビルド依存関係を追加します。

シグナルを確認する

アダプターがシグナルを送信していることを確認するには、ネットワークプロキシを使用して、アプリの広告リクエストトラフィックをモニタリングします。成功すると、各広告リクエストにシグナルが表示されます。

完全な例を確認する

このセクションでは、すべての手順の完成例を紹介します。この例は、今後の参考として使用できます。

package companydomain.path.to.securesignals;
import android.content.Context;
import androidx.annotation.Keep;
import com.google.ads.interactivemedia.v3.api.VersionInfo;
import com.google.ads.interactivemedia.v3.api.signals.SecureSignalsAdapter;
import com.google.ads.interactivemedia.v3.api.signals.SecureSignalsCollectSignalsCallback;
import com.google.ads.interactivemedia.v3.api.signals.SecureSignalsInitializeCallback;

/**
 * An example implementation of Secure Signals adapter.
 */
@Keep
public final class MySecureSignalsAdapter implements SecureSignalsAdapter {
  /**
   * Specifies this adapter's version.
   */
  private static final VersionInfo AdapterVersion = new VersionInfo(1, 0, 1);
  /**
   * Default constructor with no arguments for IMA SDK to instantiate this class.
   */
  public MySecureSignalsAdapter() {
  }
  /**
   * Initialize your SDK and any dependencies.
   * IMA SDK calls this function exactly once before signal collection.
   *
   * @param context  The activity context that creates an ads loader.
   * @param callback A callback function to pass initialization results to IMA SDK.
   */
  @Override
  public void initialize(Context context, SecureSignalsInitializeCallback callback) {
    try {
      // Initialize your SDK and any dependencies.
      ...

      // Notify IMA SDK of initialization success.
      callback.onSuccess();
    } catch (Exception e) {
      // Pass initialization failures to IMA SDK.
      callback.onFailure(e);
    }
  }
  /**
   * Invokes your SDK to collect, encrypt and send the signal collection results to IMA SDK.
   * IMA SDK calls this function before each ad request.
   *
   * @param context  The activity context that creates an ads loader.
   * @param callback A callback function to pass signal collection results to IMA SDK.
   */
  @Override
  public void collectSignals(Context context, SecureSignalsCollectSignalsCallback callback) {
    try {
      // Collect and encrypt the signals.
      String signals = ...;

      // Pass the encrypted signals to IMA SDK.
      callback.onSuccess(signals);
    } catch (Exception e) {
      // Pass signal collection failures to IMA SDK.
      callback.onFailure(e);
    }
  }
  /**
   * @return The version of this adapter.
   * IMA SDK calls this function before each ad request.
   */
  @Override
  public VersionInfo getVersion() {
    return AdapterVersion;
  }
  /**
   * @return The version of your SDK that this adapter is depending on.
   * IMA SDK calls this function before each ad request.
   */
  @Override
  public VersionInfo getSDKVersion() {
    // Request the version from your SDK and convert to an IMAVersion.
    int[] mySDKVersion = ...;
    return new VersionInfo(mySDKVersion[0], mySDKVersion[1], mySDKVersion[2]);
  }
}