安全信号是客户端设备收集并与特定出价方共享的经过编码的数据。本页将指导您使用互动式媒体广告 (IMA) SDK 收集安全信号并将其发送到 Google Ad Manager。
准备工作
在继续之前，请确保您使用的是 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 会通过调用适配器的初始化方法，对每个适配器进行一次初始化。实现此方法可开始任何加密依赖项、设置缓存或预计算所有信号收集调用中保持不变的任何信号。
以下示例会初始化适配器：
...
/**
* 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' }添加 build 依赖项，例如适配器和 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]);
}
}