Создайте безопасный адаптер сигналов

Выберите платформу: Android iOS

Secure signals are encoded data a client device collects and shares with select bidders. This page guides you on collecting and sending secure signals to Google Ad Manager using the Interactive Media Ads (IMA) SDK.

Прежде чем начать

Прежде чем продолжить, убедитесь, что у вас установлен IMA SDK для Android версии 3.29.0 или выше.

Создайте интерфейс защищенного адаптера сигнала.

Для сбора и передачи защищенных сигналов создайте классы, реализующие следующий интерфейс:

Примечание: SDK IMA загружает ваш класс адаптера с помощью рефлексии. Чтобы предотвратить удаление минифицированного кода во время сборки, добавьте к вашему классу аннотацию Android @Keep .

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() {
  }
}

Инициализируйте адаптер.

The IMA SDK initializes each adapter once by calling the initialization method of the adapter. Implement this method to begin any encryption dependencies, set up caches, or pre-calculating any signals that remain the same in all signal collection calls.

Следующий пример инициализирует адаптер:

  ...
  /**
   * 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."));
  }
  ...

Сбор сигналов

Before an ad request initiates, the IMA SDK calls a collect signals method asynchronously. These signal collector methods contain a callback function to pass the encrypted signals or report an error.

Note: Within 500 milliseconds, you must complete the signal collection, encryption, and pass the encrypted signal to the callback function. After 500 milliseconds, the IMA SDK discards any signal collection.

В следующих примерах осуществляется сбор защищенных сигналов через функцию обратного вызова:

  ...
  /**
   * 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);
    }
  }
  ...

Сообщить об ошибках

To communicate with users who use your adapter class, report all errors during the signal collection and pass them to the signal collector callback. This process troubleshoots issues that occur during integration of your adapter to applications.

Возможны следующие ошибки:

• В приложении не найден ваш 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.

You can design your adapter to work with multiple versions of your SDK. For the adapter to work with multiple versions, verify you return the runtime version of the SDK. In each ad request, the IMA SDK includes the runtime version with the adapter version.

В следующих примерах запрашивается и возвращается версия среды выполнения 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 в Google. SDK IMA инициализирует только те адаптеры, которые вы зарегистрировали в Google.

Проверьте адаптер.

Для проверки работоспособности адаптера выполните следующие действия:

Настройте тестовое приложение.

Перед проверкой адаптера настройте тестовое приложение. Выполните следующие шаги:

1. Добавьте зависимости для IMA SDK в файл Gradle на уровне приложения вашего модуля, например, в app/build.gradle :

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

2. Добавьте зависимости для сборки, такие как ваш адаптер и 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]);
  }
}