Разработка адаптера для торгов

Это руководство предназначено для рекламных сетей, которые хотят создать адаптер ставок для участия в назначении ставок в режиме реального времени (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);
}

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

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

Таймаут: 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();
}

собирать сигналы()

Таймаут: 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 для загрузки этого объявления.

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

Формат объявления Метод загрузки
Баннер loadBannerAd()
Межстраничный loadInterstitialAd()
Награжден loadRewardedAd()

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

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

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

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

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

Метод mediationAdLoadCallback.onSuccess() требует, чтобы вы передали объект, который подтверждает один из интерфейсов «Реклама», определенных 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 the 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 регистрирует показ нативного объявления, когда виден 1 пиксель объявления. Если 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, ...);
  }
}