Tworzenie adaptera ustalania stawek

Ten przewodnik jest przeznaczony dla sieci reklamowych, które chcą utworzyć adapter do określania stawek, aby uczestniczyć w określaniu stawek w czasie rzeczywistym w ramach zapośredniczenia Google. Jeśli jesteś wydawcą, zapoznaj się z instrukcjami dotyczącymi mediacji wydawców.

Adapter określania stawek to część integracji po stronie klienta. Adapter umożliwia pakietowi SDK sieci reklamowej komunikację z pakietem SDK do reklam mobilnych Google w celu wczytywania reklam wyświetlanych przez Twojego oferenta.

Aby ustalanie stawek działało prawidłowo, adapter musi obsługiwać inicjowanie, zbieranie sygnałów, wczytywanie reklam i przekazywanie zdarzeń związanych z cyklem życia reklamy. W tym przewodniku pokażemy, jak należy wdrożyć adapter, aby obsługiwał te operacje.

Uwaga: udział w licytacji wymaga też licytującego, który może odpowiadać na żądania OpenRTB. Instrukcje dotyczące uruchamiania licytującego wykraczają poza zakres tego przewodnika.

Proces adaptera do określania stawek

Zdarzenie inicjujące

Poniżej znajdziesz szczegółowy przepływ całego cyklu życia żądania, odpowiedzi i renderowania adaptera:

Adapter odpowiada za te części procesu:

• Kroki 4–7. Zainicjuj adapter i wywołaj zwrotnie pakiet SDK do reklam mobilnych Google po zakończeniu inicjowania.

• Kroki 10–13. Zbierz sygnały z pakietu SDK sieci reklamowej, aby wysłać je do podmiotu ustalającego stawki w celu uczestniczenia w żądaniu RTB, i przekaż je do pakietu SDK do reklam mobilnych Google.

• Kroki 18–21. Jeśli licytujący zwróci zwycięską stawkę, wczytaj reklamę zgodnie z odpowiedzią licytującego. Po wczytaniu powiadom pakiet SDK do reklam mobilnych Google, że reklama została wczytana.

• Krok 23 i późniejsze: podczas wyświetlania reklamy powiadamiaj pakiet SDK do reklam mobilnych Google o zdarzeniach wyświetlenia i kliknięcia, a także o innych zdarzeniach związanych z reklamą, które występują w trakcie jej wyświetlania.

Uwaga: pakiet SDK do reklam mobilnych Google oddzielnie śledzi zdarzenia wyświetleń, ale ważne jest też, aby przekazywać zdarzenie wyświetlenia sieci reklamowej, abyśmy mogli sprawdzać rozbieżności.

Wdrażanie adaptera do określania stawek

Aby utworzyć adapter do określania stawek dla pakietu SDK do reklam mobilnych Google, musisz rozszerzyć klasę abstrakcyjną RtbAdapter. W sekcjach poniżej znajdziesz opis każdej metody abstrakcyjnej w RtbAdapter.

getSDKVersionInfo()

W tym miejscu należy zwrócić wersję pakietu SDK. Ta wersja jest przekazywana do licytującego w ramach żądania OpenRTB.

Ta metoda wymaga zwrotu urządzenia VersionInfo. Poniższy przykład pokazuje, jak przekonwertować wersję ciągu pakietu SDK na 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()

W tym miejscu należy zwrócić wersję adaptera. Ta wersja jest przekazywana do licytującego w ramach żądania OpenRTB.

Adaptery Google o otwartym kodzie źródłowym i wersjonowane używają 4-cyfrowego schematu wersji adaptera, ale VersionInfo dopuszcza tylko 3 cyfry. Aby temu zapobiec, zalecamy połączenie 2 ostatnich cyfr w wersję poprawki, jak pokazano poniżej.

@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()

Czas oczekiwania: 30 sekund

Metoda initialize() jest pierwszą metodą wywoływaną w adapterze. Jest ona wywoływana tylko raz na sesję. Ta metoda zwraca listę obiektów MediationConfiguration, które reprezentują pełną listę miejsc docelowych w tej aplikacji skonfigurowanych dla Twojej sieci reklamowej. Możesz przejść przez tę listę, aby przeanalizować dane logowania dla każdego miejsca docelowego, i przekazać odpowiednie dane do pakietu SDK w celu inicjowania.

Gdy pakiet SDK zostanie zainicjowany i będzie gotowy do odbierania żądań reklam, wywołaj metodę onInitializationSucceeded() obiektu InitializationCompleteCallback. To wywołanie zwrotne jest przekazywane do wydawców aplikacji, aby mogli oni wiedzieć, że mogą rozpocząć wczytywanie reklam.

Uwaga: metoda initialize() jest wywoływana w przypadku instancji adaptera, która jest używana tylko raz. W przypadku tej instancji nie będą wywoływane żadne inne metody. Jeśli w wyniku tej metody adapter musi zapisać stan, powinien on być statyczny.

@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()

Czas oczekiwania: 1 sekunda

Za każdym razem, gdy wydawca zażąda reklamy, tworzona jest nowa instancja RtbAdapter i wywoływana jest metoda collectSignals(). Ta instancja parametru RtbAdapter będzie używana przez cały cykl życia żądania reklamy, odpowiedzi i renderowania tej reklamy. Metoda collectSignals() umożliwia Twojemu adapterowi dostarczanie sygnałów z urządzenia, które mają być wysyłane do licytującego w żądaniu OpenRTB.

collectSignals() jest wywoływana w wątku w tle. Pakiet SDK do reklam mobilnych Google jednocześnie wysyła żądania sygnałów do wszystkich adapterów biorących udział w określaniu stawek. W tym czasie zachowaj ostrożność i ogranicz wywołania do wątku interfejsu. Wszelkie wymagające duże nakłady pracy działania, które adapter lub SDK musi wykonać, aby zebrać sygnały, powinny być wykonywane w metodzie initialize() i przechowywane w pamięci podręcznej.

Gdy sygnały będą gotowe, wywołaj funkcję onSuccess()callback z zakodowanymi sygnałami.

Oto przykładowy kod:

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

Jeśli adapter nie zbiera sygnałów, wywołaj funkcję signalCallbacks.onFailure(), przekazując ciąg znaków z wyjaśnieniem, jaki błąd wystąpił.

Uwaga: ciąg sygnałów może reprezentować dowolny obiekt i może mieć dowolny format, np. zwykły JSON, zakodowany w Base64 lub dowolną inną formę szyfrowania. Szyfrowanie sygnałów jest zalecane, aby zapewnić, że sygnały są nieprzejrzyste poza Twoją siecią.

Wdrażanie metod wczytywania reklam

Czas oczekiwania: 10 sekund

Jeśli system licytujący zwróci zwycięską stawkę, pakiet SDK do reklam mobilnych Google wywoła Twój adapter, aby wczytać zwycięską reklamę, przekazując Ci wszelkie dane zwrócone przez system licytujący, które są potrzebne pakietowi SDK do wczytania tej reklamy.

Dokładna metoda wczytywania, która jest wywoływana, zależy od formatu reklamy, do którego odnosi się to żądanie:

Format reklamy	Metoda ładowania
Baner	loadBannerAd()
Pełnoekranowa	loadInterstitialAd()
Z nagrodą	loadRewardedAd()

Zaimplementuj te metody w przypadku formatów reklam obsługiwanych przez Twój adapter.

Metoda load jest wywoływana w wątku interfejsu na tej samej instancji adaptera, z której zostały dostarczone sygnały. Ta metoda udostępnia te parametry:

• MediationAdConfiguration, który zawiera parametry potrzebne pakietowi SDK do wczytania reklamy w przypadku wygranej stawki, np. odpowiedź na pytanie o stawkę i wszelkie dane logowania skonfigurowane przez wydawcę w interfejsie AdMob.

• Obiekt MediationAdLoadCallback służący do powiadamiania pakietu SDK do reklam mobilnych Google o tym, czy wczytywanie się powiodło, czy nie.

Gdy pakiet SDK wczyta reklamę, wywołaj funkcję mediationAdLoadCallback.onSuccess(). Jeśli wczytywanie reklamy się nie powiedzie, wywołaj funkcję mediationAdLoadCallback.onFailure() z ciągiem znaków wyjaśniającym, jaki błąd wystąpił.

Metoda mediationAdLoadCallback.onSuccess() wymaga przekazania obiektu zgodnego z jednym z interfejsów „Ad” zdefiniowanych przez pakiet SDK do reklam mobilnych Google. Interfejsy reklam proszą o podanie pewnych informacji o reklamie.

MediationAdConfiguration ma też metodę getWatermark(), która zwraca ciąg tekstowy zakodowany w formacie Base64 reprezentujący obraz PNG. Ten obraz powinien być wyświetlany w postaci kafelków w przezroczystej nakładce na reklamach. Aby uzyskać dodatkowe wskazówki dotyczące renderowania znaku wodnego, skontaktuj się z Google. Zawiera metadane dotyczące wyświetlanej reklamy, które wydawcy mogą wykorzystywać do określania źródła wyświetlanych reklam.

W przypadku banerów poprosimy Cię o podanie widoku banera. W przypadku reklam pełnoekranowych i reklam z nagrodą musisz zaimplementować metodę show(), aby wyświetlać reklamę w późniejszym czasie. Zgodnie ze sprawdzoną metodą klasa, która wczytuje reklamy, powinna też implementować te metody reklamowe.

Poniżej znajdziesz przykładową implementację loadBannerAd(). Pamiętaj, że implementacja Twojego adaptera będzie wyglądać inaczej, ponieważ adapter jest zintegrowany z innym pakietem 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;
  }
}

Przekazywanie zdarzeń cyklu życia prezentacji reklamy

Ostateczną odpowiedzialnością adaptera jest powiadamianie pakietu SDK do reklam mobilnych Google o wszelkich zdarzeniach cyklu życia wyświetlania, aby można je było przekazywać wydawcy. Wydawca oczekuje tych wywołań zwrotnych w określonych momentach, niezależnie od tego, która sieć reklamowa wyświetla reklamę. Dlatego ważne jest, aby jak najwięcej z nich było wywoływanych w odpowiednim czasie, tak aby pakiet SDK do reklam mobilnych Google mógł je przekazywać wydawcy.

W odpowiednich przypadkach adaptery powinny wywoływać te zdarzenia:

Wspólne dla wszystkich formatów
Metoda	Kiedy dzwonić
reportAdClicked()	Reklama została kliknięta.
reportAdImpression()	Reklama wygenerowała wyświetlenie.
onAdOpened()	Reklama była wyświetlana na pełnym ekranie.
onAdClosed()	Widok pełnoekranowy reklamy został zamknięty.
onAdLeftApplication()	Reklama spowodowała opuszczenie aplikacji przez użytkownika.
Reklamy z nagrodą
onRewarded()	Użytkownik otrzymuje nagrodę.
Wywołania zwrotne wideo (reklamy z nagrodą i reklamy natywne)
onVideoStarted()	Rozpoczęło się odtwarzanie filmu z reklamą.
onVideoCompleted()	Film z reklamą został odtworzony do końca.

Po wywołaniu funkcji mediationAdLoadCallback.onSuccess() adapter otrzymuje obiekt MediationAdLoadCallback<MediationAdT, MediationAdCallbackT>. Adaptery powinny przechowywać ten obiekt i używać go do wywoływania zdarzeń wyświetlania, które występują w Twojej reklamie.

Większość tych zdarzeń jest zwykle wywoływana przez pakiet SDK sieci reklamowej. Rola adaptera polega po prostu na mapowaniu wywołań zwrotnych z pakietu SDK sieci reklamowej na pakiet SDK do reklam mobilnych Google.

Poniższy przykład pokazuje, jak przekazywać wywołania zwrotne z odsłuchu reklam w pakiecie SDK do pakietu SDK do reklam mobilnych Google:

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

Wymagane komponenty do śledzenia wyświetleń reklam natywnych

Pakiet SDK do reklam mobilnych Google rejestruje wyświetlenie reklamy natywnej, gdy widoczny jest 1 piksel reklamy. Jeśli pakiet SDK sieci reklamowej wymaga wyświetlania określonych komponentów, aby można było zarejestrować prawidłowe wyświetlenie, licytujący może wskazać te wymagane komponenty natywne w odpowiedzi na żądanie stawki. Pakiet SDK do reklam mobilnych Google sprawdza następnie, czy wymagane komponenty natywne są wyświetlane przed zarejestrowaniem wyświetlenia.

Więcej informacji o tym, jak określać dodatkowe wymagane komponenty w odpowiedzi na ofertę, znajdziesz w dokumentacji dotyczącej wymaganych komponentów natywnych.

Ważna informacja: wszelkie wyświetlenia unieważnione z powodu dodatkowych komponentów natywnych wymaganych przez Twoją sieć reklamową wpłyną na współczynnik zdarzeń podlegających rozliczeniu w przypadku danego wydawcy.

Wyświetlanie błędów reklam

W przypadku formatów pełnoekranowych, takich jak reklamy pełnoekranowe i reklamy z nagrodą, w wywołaniu zwrotnym load w przypadku powodzenia podasz implementację MediationInterstitialAd lub MediationRewardedAd, aby pakiet SDK do reklam mobilnych Google mógł poprosić Twój adapter o wyświetlenie reklamy.

Pakiet SDK do reklam mobilnych Google zakłada, że jeśli adapterowi udało się wczytać reklamę, jest ona gotowa do wyświetlenia, gdy wydawca o to poprosi. Oznacza to, że każde wywołanie wyświetlenia powinno skutkować wyświetleniem.

W niektórych przypadkach wyświetlenie reklamy może być niemożliwe. Jeśli nie możesz wyświetlić reklamy, wywołaj funkcję zwrotną onAdFailedToShow(), aby anulować wyświetlenie.

Tabela poniżej pokazuje, jak wywołania zwrotne dotyczące prezentacji wpływają na rejestrowanie wyświetleń w przypadku formatów reklam pełnoekranowych:

Oddzwanianie	Wynik
onAdOpened()	Impression recorded
onAdFailedToShow()	Impression failure^1
Żadna z powyższych przez kilka sekund	Impression recorded

¹ W przypadku nieudanych wyświetleń sieć reklamowa nie jest obciążana opłatą za wyświetlenie, ale ma to wpływ na korektę stawki zdarzeń podlegających rozliczeniu. Więcej informacji znajdziesz w sekcji sygnały w żądaniu stawki.

Poniższy przykład pokazuje cykl życia wczytywania i wyświetlania, w którym wywołanie wyświetlenia reklamy może zakończyć się niepowodzeniem.

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