セキュア シグナルは、クライアント デバイスが収集して一部のビッダーと共有するエンコードされたデータです。このページでは、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]);
}
}