此页面由 Cloud Translation API 翻译。

创建安全信号适配器

安全信号是指客户端设备收集并与所选设备共享的经过编码的数据出价工具。本页将指导您使用互动式媒体广告 (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]);
  }
}