Эта страница переведена с помощью Cloud Translation API.

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

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

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

Прежде чем продолжить, убедитесь, что у вас установлен IMA SDK для Android версии 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 или в Google. IMA SDK инициализирует только те адаптеры, которые вы регистрируете в Google.

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

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

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

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

Добавьте зависимости для IMA SDK в файл Gradle уровня приложения вашего модуля, например app/build.gradle :
```
dependencies {
  implementation 'com.google.ads.interactivemedia.v3:interactivemedia:3.29.0'
}
```
Добавьте зависимости сборки, такие как адаптер и 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]);
  }
}