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

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

Защищённые сигналы — это закодированные данные, которые клиентское устройство собирает и передает выбранным участникам торгов. Эта страница содержит инструкции по сбору и отправке защищённых сигналов в Google Ad Manager с помощью Interactive Media Ads (IMA) SDK.

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

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

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

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

Примечание: IMA SDK загружает класс адаптера с помощью рефлексии. Чтобы предотвратить удаление минифицированного кода во время сборки, добавьте к классу аннотацию 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() {
  }
}

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

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 асинхронно вызывает метод сбора сигналов. Эти методы сбора сигналов содержат функцию обратного вызова для передачи зашифрованных сигналов или сообщения об ошибке.

Примечание: В течение 500 миллисекунд необходимо завершить сбор сигнала, его шифрование и передать зашифрованный сигнал функции обратного вызова. По истечении 500 миллисекунд 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 или в Google. IMA SDK инициализирует только те адаптеры, которые вы зарегистрировали в 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]);
  }
}