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

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

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

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

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

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

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

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

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

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

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

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

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

Чтобы создать адаптер для ставок в 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);
}

получитьVersionInfo()

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

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

@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);
}

инициализировать()

Тайм-аут: 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 секунд

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

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

Формат рекламы Метод загрузки
Баннер loadBannerAd()
Интерстициальный loadInterstitialAd()
Награжден loadRewardedAd()

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

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

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

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

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

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

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 мог переслать их издателю.

Адаптеры должны вызывать следующие события, когда это применимо:

Общее для всех форматов
Метод Когда звонить
reportAdClicked() На объявление кликнули.
reportAdImpression() Реклама произвела впечатление.
onAdOpened() Реклама показывалась в полноэкранном режиме.
onAdClosed() Полноэкранный просмотр объявления закрыт.
onAdLeftApplication() Реклама заставила пользователя выйти из приложения.
Реклама с вознаграждением
onRewarded() Пользователю предоставляется вознаграждение.
Видеообратные вызовы (реклама с вознаграждением и нативная реклама)
onVideoStarted() Начался показ рекламного ролика.
onVideoCompleted() Рекламный видеоролик завершен.

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

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

В следующем примере показано, как перенаправить обратные вызовы из прослушивателя объявлений вашего 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 регистрирует показ нативного объявления, когда видна только его часть. Если SDK вашей рекламной сети требует отображения определённых ресурсов для корректного показа, ваш участник торгов может указать эти необходимые ресурсы в ответе на запрос ставки. Затем Google Mobile Ads SDK проверяет отображение требуемых ресурсов перед регистрацией показа.

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

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

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

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

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

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

Перезвонить Результат
onAdOpened() Impression recorded
onAdFailedToShow() Impression failure 1
Ничего из вышеперечисленного в течение нескольких секунд Impression recorded

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