本頁面由 Cloud Translation API 翻譯而成。

建立安全信號轉接器

安全信號是指用戶端裝置收集的資料，並與特定出價者共用的資料。本頁面將引導您使用互動式媒體廣告 (IMA) SDK，收集並傳送安全信號給 Google Ad Manager。

事前準備

繼續操作前，請確認您已安裝 Android 適用的 IMA 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 註冊 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]);
  }
}