安全信號是用戶端裝置收集並與特定出價方共用的編碼資料。本頁面說明如何使用互動式媒體廣告 (IMA) SDK，收集安全信號並傳送至 Google Ad Manager。
事前準備
繼續操作前，請確認您使用的是 IMA Android SDK 3.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 會呼叫轉接程式的初始化方法，為每個轉接程式初始化一次。實作這個方法，即可開始處理任何加密依附元件、設定快取，或預先計算所有信號收集呼叫中保持不變的信號。
以下範例會初始化轉接程式：
...
/**
* 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 介面卡收集信號，您必須向 Google 註冊 Android 套件名稱或 。IMA SDK 只會初始化您向 Google 註冊的轉接程式。
驗證轉接器
如要驗證轉接器，請完成下列各節：
設定測試應用程式
驗證轉接程式前，請先設定測試應用程式。請完成下列步驟：
將 IMA SDK 的依附元件新增至模組的應用程式層級 Gradle 檔案，例如
app/build.gradle：dependencies { implementation 'com.google.ads.interactivemedia.v3:interactivemedia:3.29.0' }新增建構依附元件，例如轉接程式和 SDK。
驗證信號
如要確認轉接程式是否會傳送信號，請使用網路 Proxy 監控應用程式的廣告請求流量。如果成功，您會在每個廣告請求中看到信號。
查看完整範例
本節會顯示所有步驟的完成範例，供您參考。
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]);
}
}