Как создать адаптер защищенных сигналов

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

Защищенные сигналы – это закодированные данные, которые клиентское устройство собирает и передает определенным системам назначения ставок. На этой странице рассказывается, как собирать и отправлять защищенные сигналы в Google Менеджер рекламы с помощью 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 Runtime:

  ...
  /**
   * @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. Добавьте зависимости сборки, например адаптер и 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]);
  }
}