创建安全信号适配器

安全信号是客户端设备收集并与特定出价方共享的经过编码的数据。本页将指导您使用互动式媒体广告 (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 注册的适配器。

验证适配器

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

配置测试应用

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

  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]);
  }
}