セキュア シグナルとは、クライアント デバイスが収集して一部の入札者と共有するエンコードされたデータです。このページでは、Interactive Media Ads（IMA）SDK を使用してセキュア シグナルを収集し、Google アド マネージャーに送信する方法について説明します。
始める前に
続行する前に、 IMA SDK for Android 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]);
}
}