创建安全信号适配器

选择平台： Android iOS

安全信号是客户端设备收集并与选定的出价方共享的编码数据。本页介绍了如何使用互动媒体广告 (IMA) SDK 收集安全信号并将其发送给 Google Ad Manager。

准备工作

在继续之前，请确认您拥有 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 会通过调用适配器的初始化方法来初始化每个适配器一次。实现此方法可开始任何加密依赖项、设置缓存或预先计算在所有信号收集调用中保持不变的任何信号。

以下示例会初始化适配器：

  ...
  /**
   * 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 注册的适配器。

验证适配器

如需验证适配器，请完成以下部分：

配置测试应用

在验证适配器之前，请先配置测试应用。请完成以下步骤：

  1. 将 IMA SDK 的依赖项添加到模块的应用级 Gradle 文件（例如 app/build.gradle）：

    dependencies {
  implementation 'com.google.ads.interactivemedia.v3:interactivemedia:3.29.0'
}

  2. 添加 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]);
  }
}