Разработка адаптера ставок

Это руководство предназначено для рекламных сетей, желающих создать адаптер для участия в торгах в режиме реального времени (RTB) в рамках системы медиации Google. Если вы являетесь издателем, ознакомьтесь с инструкциями по медиации для издателей .

Адаптер для размещения ставок — это клиентская часть интеграции. Адаптер позволяет вашему SDK рекламной сети взаимодействовать с Google Mobile Ads SDK для загрузки объявлений, показываемых вашим адаптером для размещения ставок.

Для корректной работы системы назначения ставок ваш адаптер должен обрабатывать инициализацию, сбор сигналов, загрузку объявлений и передачу событий жизненного цикла объявления. В этом руководстве мы расскажем, как следует реализовать ваш адаптер для обработки этих операций.

Рабочий процесс адаптера торгов

Инициализация

Ниже представлен подробный алгоритм всего жизненного цикла адаптера: запрос-ответ-рендеринг:

Адаптер отвечает за следующие этапы рабочего процесса:

• Шаги 4-7: Инициализируйте адаптер и вызовите Google Mobile Ads SDK после завершения инициализации.

• Шаги 10-13: Соберите сигналы из SDK вашей рекламной сети, чтобы отправить их вашему участнику торгов для участия в запросе RTB, и перенаправьте их в SDK мобильной рекламы Google.

• Шаги 18-21: Если ваш участник торгов предложит выигрышную ставку, загрузите объявление в соответствии с ответом участника торгов. После загрузки уведомите Google Mobile Ads SDK о том, что объявление загружено.

• Шаг 23 и последующие: Во время показа вашего объявления отправляйте уведомления в SDK Google Mobile Ads о показах и кликах, а также о других событиях, происходящих в течение жизненного цикла показа вашего объявления.

Реализация адаптера для торгов

Для создания адаптера для размещения ставок в Google Mobile Ads SDK необходимо расширить абстрактный класс RtbAdapter . В следующих разделах описан каждый абстрактный метод в RtbAdapter .

getSDKVersionInfo()

Здесь следует вернуть версию вашего SDK. Эта версия передается вашему участнику торгов в рамках запроса OpenRTB.

Этот метод требует возврата объекта VersionInfo . В приведенном ниже примере показано, как можно преобразовать строковую версию вашего SDK в объект VersionInfo.

@Override
public VersionInfo getSDKVersionInfo() {
  // Get your SDK's version as a string. E.g. "1.2.3"
  // String versionString = YourSdk.getVersion();
  String splits[] = versionString.split("\\.");
  if (splits.length >= 3) {
      int major = Integer.parseInt(splits[0]);
      int minor = Integer.parseInt(splits[1]);
      int micro = Integer.parseInt(splits[2]);
      return new VersionInfo(major, minor, micro);
   }

   String logMessage = String.format("Unexpected SDK version format: %s." +
           "Returning 0.0.0 for SDK version.", sdkVersion);
   Log.w(TAG, logMessage);
   return new VersionInfo(0, 0, 0);
}

getVersionInfo()

Здесь вам следует вернуть версию вашего адаптера. Эта версия передается вашему участнику торгов в рамках запроса OpenRTB.

В адаптерах Google с открытым исходным кодом и версионированных адаптерах используется 4-значная схема версии адаптера, но VersionInfo допускает только 3 цифры. Чтобы обойти это ограничение, рекомендуется объединить две последние цифры в версию патча, как показано ниже.

@Override
public VersionInfo getVersionInfo() {
  // Get your adapters's version as a string. E.g. "1.2.3.0"
  String versionString = BuildConfig.VERSION_NAME;
  String splits[] = versionString.split("\\.");
  if (splits.length >= 4) {
      int major = Integer.parseInt(splits[0]);
      int minor = Integer.parseInt(splits[1]);
      int micro = Integer.parseInt(splits[2]) * 100 + Integer.parseInt(splits[3]);
      return new VersionInfo(major, minor, micro);
    }

    String logMessage = String.format("Unexpected adapter version format: %s." +
                "Returning 0.0.0 for adapter version.", versionString);
    Log.w(TAG, logMessage);
    return new VersionInfo(0, 0, 0);
}

initialize()

Тайм-аут: 30 секунд

Метод initialize() — первый метод, вызываемый в вашем адаптере. Он вызывается только один раз за сессию. Этот метод предоставляет вам список объектов MediationConfiguration , представляющих полный список мест размещения рекламы в этом приложении, настроенных для вашей рекламной сети; вы можете пройтись по этому списку в цикле, чтобы проанализировать учетные данные для каждого места размещения и передать соответствующие данные в ваш SDK для инициализации.

После инициализации вашего SDK и его готовности к приему рекламных запросов вызовите метод onInitializationSucceeded() объекта InitializationCompleteCallback . Этот коллбэк перенаправляется издателям приложений, чтобы они знали, что могут начать загрузку рекламы.

@Override
public void initialize(Context context,
    InitializationCompleteCallback initializationCompleteCallback,
    List<MediationConfiguration> mediationConfigurations) {
  // Initialize your ad network's SDK.
  ...

  // Invoke the InitializationCompleteCallback once initialization completes.
  initializationCompleteCallback.onInitializationSucceeded();
}

collectSignals()

Тайм-аут: 1 секунда

Каждый раз, когда издатель запрашивает рекламу, создается новый экземпляр вашего RtbAdapter и вызывается метод collectSignals() . Этот экземпляр RtbAdapter будет использоваться на протяжении всего жизненного цикла запроса, ответа и отрисовки рекламы. Метод collectSignals() позволяет вашему адаптеру передавать сигналы с устройства для отправки вашему участнику торгов в запросе OpenRTB.

collectSignals() вызывается в фоновом потоке. Google Mobile Ads SDK одновременно запрашивает сигналы у всех адаптеров, участвующих в торгах. Пожалуйста, соблюдайте правила и ограничивайте вызовы в потоке пользовательского интерфейса в это время. Любая ресурсоемкая работа, которую ваш адаптер или SDK должен выполнять для сбора сигналов, должна выполняться в методе initialize() и кэшироваться.

Как только ваши сигналы будут готовы, вызовите функцию обратного вызова onSuccess() с закодированными сигналами.

Вот пример реализации:

@Override
public void collectSignals(RtbSignalData rtbSignalData,
                           SignalCallbacks signalCallbacks) {
  String signals = YourSdk.getSignals();
  signalCallbacks.onSuccess(signals);
}

Если ваш адаптер не может собирать сигналы, вызовите метод signalCallbacks.onFailure() и передайте строку с описанием произошедшей ошибки.

Внедрить методы загрузки рекламы.

Тайм-аут: 10 секунд

Если ваш участник торгов возвращает выигрышную ставку, Google Mobile Ads SDK вызывает ваш адаптер для загрузки выигрышного объявления, передавая вам все данные, возвращенные участником торгов, которые необходимы вашему SDK для загрузки этого объявления.

Точный метод загрузки, который будет вызван, зависит от формата объявления, для которого предназначен этот запрос:

Реализуйте эти методы для форматов рекламы, поддерживаемых вашим адаптером.

Метод `load` вызывается в потоке пользовательского интерфейса, в том же экземпляре адаптера, из которого вы передавали сигналы. Этот метод предоставляет вам следующие параметры:

• Объект MediationAdConfiguration содержит параметры, необходимые вашему SDK для загрузки объявления для выигрышной ставки, такие как ответ на ставку и любые учетные данные, настроенные издателем в пользовательском интерфейсе AdMob.

• Объект MediationAdLoadCallback , используемый для уведомления Google Mobile Ads SDK об успешной или неудачной загрузке.

После загрузки рекламы с помощью SDK вызовите метод mediationAdLoadCallback.onSuccess() . В случае неудачной загрузки рекламы вызовите метод mediationAdLoadCallback.onFailure() , передав строку с описанием возникшей ошибки.

Метод mediationAdLoadCallback.onSuccess() требует передачи объекта, подтверждающего соответствие одному из интерфейсов "Ad", определенных SDK мобильной рекламы Google. Эти интерфейсы запрашивают у вас некоторую информацию о рекламе.

MediationAdConfiguration также есть метод getWatermark() , который возвращает строку в кодировке base64, представляющую собой изображение PNG. Это изображение должно быть размещено в виде прозрачного слоя поверх ваших объявлений. Обратитесь в Google за дополнительными рекомендациями по отображению водяного знака. Он содержит метаданные о показываемом объявлении, которые издатели используют для определения источника показа рекламы.

Для баннеров вам будет предложено указать представление баннера. Для межстраничной и рекламной рекламы с вознаграждением вам будет предложено реализовать метод show() для отображения рекламы позже. В качестве лучшей практики мы рекомендуем, чтобы ваш класс, отвечающий за загрузку рекламы, также отвечал за реализацию этих методов для рекламы.

Ниже приведен пример реализации функции loadBannerAd() . Имейте в виду, что реализация в вашем адаптере будет выглядеть иначе, поскольку ваш адаптер интегрируется с другим SDK.

public final class SampleRtbAdapter extends RtbAdapter {
  ...

  @Override
  public void loadBannerAd(
      MediationBannerAdConfiguration adConfiguration,
      MediationAdLoadCallback<MediationBannerAd, MediationBannerAdCallback> callback) {

      SampleBannerRenderer bannerRenderer =
          new SampleBannerRenderer(adConfiguration, callback);
      bannerRenderer.render();
    }
}

// Renders a banner ad, and forwards callbacks to Google Mobile Ads SDK.
public class SampleBannerRenderer implements MediationBannerAd {
  private MediationBannerAdConfiguration adConfiguration;
  private final MediationAdLoadCallback<MediationBannerAd, MediationBannerAdCallback> adLoadCallback;
  private AdView adView;
  private MediationBannerAdCallback callback;

  public SampleRtbBannerRenderer(
      MediationBannerAdConfiguration adConfiguration,
      MediationAdLoadCallback<MediationBannerAd, MediationBannerAdCallback> adLoadCallback) {
    this.adConfiguration = adConfiguration;
    this.adLoadCallback = adLoadCallback;
  }

  public void render() {
    adView = new AdView(adConfiguration.getContext());
    adView.setAdSize(adConfiguration.getAdSize());
    // serverParameters are the parameters entered in the AdMob UI for your network.
    adView.setAdUnitId(adConfiguration.getServerParameters().getString("adUnitId"));

    // Map the callbacks from your SDK to Google's SDK.
    adView.setAdListener(new AdListener() {
      // See the next step for more information on callback mapping.
      // ...
    });

    // Get the bid response and watermark from the ad configuration and
    // pass the relevant information to your SDK.
    String ad = adConfiguration.getBidResponse();
    String watermark = adConfiguration.getWatermark();
    Bundle extras = new Bundle();
    extras.putString("bid", ad);
    extras.putString("watermark", watermark);
    AdRequest request = new AdRequest.Builder()
        .addNetworkExtrasBundle(AdMobAdapter.class, extras)
        .build();
    adView.loadAd(request);
  }

  // MediationBannerAd implementation

  @NonNull
  @Override
  public View getView() {
    return adView;
  }
}

События жизненного цикла презентации ретрансляционной рекламы

Конечная задача адаптера — уведомлять Google Mobile Ads SDK о любых событиях жизненного цикла показа рекламы, чтобы они могли быть перенаправлены издателю. Издатель ожидает этих обратных вызовов в определенное время независимо от того, какая рекламная сеть показывает рекламу, поэтому важно, чтобы как можно больше таких обратных вызовов было вызвано в нужное время, чтобы Google Mobile Ads SDK мог перенаправить их издателю.

При необходимости адаптеры должны вызывать следующие события:

При вызове метода mediationAdLoadCallback.onSuccess() адаптер получает объект MediationAdLoadCallback<MediationAdT, MediationAdCallbackT> . Предполагается, что адаптеры будут хранить этот объект и использовать его для вызова событий отображения, происходящих в вашей рекламе.

Как правило, большинство этих событий инициируется SDK вашей рекламной сети. Роль адаптера заключается просто в сопоставлении обратных вызовов из SDK вашей рекламной сети с Google Mobile Ads SDK .

Следующий пример демонстрирует, как можно перенаправлять обратные вызовы из обработчика рекламы вашего SDK в Google Mobile Ads SDK :

adView.setAdListener(new AdListener() {
    public void onAdLoaded() {
        callback = adLoadCallback.onSuccess(SampleBannerRenderer.this);
    }

    public void onAdImpression() {
        if (callback != null) {
            callback.reportAdImpression();
        }
    }

    public void onAdFailedToLoad(LoadAdError adError) {
        adLoadCallback.onFailure("Error: " + adError.toString());
    }

    public void onAdClosed() {
        if (callback != null) {
            callback.onAdClosed();
        }
    }

    public void onAdOpened() {
        if (callback != null) {
            callback.onAdOpened();
            callback.reportAdClicked();
        }
    }

    public void onAdLeftApplication() {
        if (callback != null) {
            callback.onAdLeftApplication();
        }
    }
});

Необходимые ресурсы для отслеживания показов нативной рекламы.

Google Mobile Ads SDK регистрирует показ нативной рекламы, когда отображается 1 пиксель объявления. Если SDK вашей рекламной сети требует отображения определенных ресурсов для корректного показа, ваш участник торгов может указать эти необходимые нативные ресурсы в ответе на запрос ставки. Затем Google Mobile Ads SDK проверяет, отображаются ли необходимые нативные ресурсы, прежде чем регистрировать показ.

Для получения дополнительной информации о том, как указать дополнительные необходимые активы в ответе на заявку, см. документацию по обязательным активам .

Показать ошибки рекламы

Для полноэкранных форматов, таких как межстраничные и рекламные объявления с вознаграждением, в функции обратного вызова при успешной загрузке необходимо указать реализацию MediationInterstitialAd или MediationRewardedAd , чтобы Google Mobile Ads SDK мог запросить у вашего адаптера показ объявления.

Google Mobile Ads SDK ожидает, что если адаптер успешно загрузил объявление, то объявление готово к показу, когда издатель запросит его отображение. Это означает, что каждый запрос на показ должен приводить к показу.

Однако могут возникнуть непредвиденные ситуации, когда показ рекламы окажется невозможным. Если показ рекламы не удаётся, вызовите функцию обратного вызова onAdFailedToShow() чтобы отменить показ.

В таблице ниже показано, как обратные вызовы при отображении влияют на запись показов для полноэкранных рекламных форматов:

^1. В случае неудачных показов ваша рекламная сеть не оплачивает показ, но это влияет на корректировку тарифа для оплачиваемых событий. Дополнительную информацию см. в разделе «Сигналы запроса ставки» .

Приведенный ниже пример демонстрирует жизненный цикл загрузки/показа рекламы, в котором вызов функции показа рекламы может привести к ошибке.

final class SampleRtbAdapter extends RtbAdapter implements MediationRewardedAd {

 private MediationRewardedAdCallback callback;
 private RewardedAd rewardedAd;

 ...

  @Override
  public void loadRewardedAd(
      MediationRewardedAdConfiguration adConfiguration,
      final MediationAdLoadCallback<MediationRewardedAd, MediationRewardedAdCallback> loadCallback) {

    // Load an ad. This mock example uses Google's SDK, but in practice
    // your adapter will load the ad using your ad network's SDK.
    RewardedAd.load(adConfiguration.getContext(),
        "ca-app-pub-3940256099942544/5224354917",
        new AdRequest.Builder().build(),
        new RewardedAdLoadCallback() {
          @Override
          public void onAdLoaded(@NonNull RewardedAd rewardedAd) {
            // When the ad loads, invoke the load success callback.
            callback = loadCallback.onSuccess(SampleRtbAdapter.this);
          }
        });
  }

  @Override
  public void showAd(Context context) {
    // In this mock example, your ad network requires an activity context, but
    // didn't receive one, making you unable to show the ad.
    if (!(context instanceof Activity)) {
      AdError error = new AdError(1, "Context must be an activity",
          "com.google.ads.mediation.sample");
      callback.onAdFailedToShow(error);
    }

    // This example shows Google SDK's callbacks, but it's likely your SDK
    // has similar presentation callbacks.
    rewardedAd.setFullScreenContentCallback(new FullScreenContentCallback() {
      @Override
      public void onAdShowedFullScreenContent() {
        // Your ad network SDK successfully showed the ad. Call onAdOpened().
        callback.onAdOpened();
      }

      @Override
      public void onAdFailedToShowFullScreenContent(AdError adError) {
        // Your ad network SDK failed to show the ad, invoke onAdFailedToShow.
        // In practice, you will map your SDK's error to an AdError.
        AdError error = new AdError(adError.getCode(), adError.getMessage(),
            adError.getDomain());
        callback.onAdFailedToShow(adError);
      }
    });


    rewardedAd.show((Activity) context, ...);
  }
}