Tworzenie adaptera stawek

Ten przewodnik jest przeznaczony dla sieci reklamowych, które chcą utworzyć adapter ustalania stawek , aby uczestniczyć w określaniu stawek w czasie rzeczywistym (RTB) w ramach zapośredniczenia Google. Jeśli jesteś wydawcą, zapoznaj się z informacjami o zapośredniczeniu wydawcy; za instrukcje.

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 wczytywać reklamy wyświetlane przez licytującego.

Aby ustalanie stawek działało prawidłowo, adapter musi inicjowanie, gromadzenie sygnałów, wczytywanie reklam i przekazywanie cyklu życia reklam zdarzeń. W tym przewodniku pokażemy, jak powinna być przejściówka do obsługi tych operacji.

Uwaga: udział w określaniu stawek wymaga też od licytującego, który może odpowiedzieć na Żądania OpenRTB. Instrukcje dotyczące tego, jak zgłosić licytującego, znajdują się poza w tym przewodniku.

Przebieg procesu korzystania z adaptera ustalania stawek

Zdarzenie inicjujące

Szczegółowy przebieg całego cyklu życia renderowania żądania i odpowiedzi przejściówki widać poniżej:

Adapter odpowiada za te etapy przepływu pracy:

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

• Kroki 10–13. Zbieraj sygnały z pakietu SDK sieci reklamowej, aby wysyłać je na licytującego do udziału w żądaniu RTB i przekazania go do Pakiet SDK do wyświetlania reklam.

• Kroki 18–21: jeśli licytujący zwróci zwycięską stawkę, wczytaj reklamę zgodnie z na odpowiedź licytującego. Po załadowaniu powiadom pakiet SDK do reklam mobilnych Google że reklama została wczytana.

• Krok 23 i późniejsze: podczas wyświetlania reklamy powiadom system Reklamy mobilne Google Pakiet SDK zdarzeń wyświetlenia i kliknięć oraz innych występujących zdarzeń reklamowych w trakcie cyklu prezentacji reklamy.

.

Uwaga: pakiet SDK do reklam mobilnych Google oddzielnie śledzi zdarzenia wyświetleń, ale ważne jest też, by zdarzenie wyświetlenia reklamy zostało skonfigurowane tak, mogą sprawdzić rozbieżności.

Wdrażanie adaptera ustalania stawek

Aby utworzyć adapter określania stawek na potrzeby pakietu SDK do reklam mobilnych Google, musisz i rozszerzenie klasy abstrakcyjnej RtbAdapter. W poniższych sekcjach wyjaśnić poszczególne metody abstrakcyjne w funkcji RtbAdapter.

getSDKVersionInfo()

W tym miejscu powinna zostać zwrócona wersja pakietu SDK. Ta wersja jest przekazywana do licytującego w ramach żądania OpenRTB.

Ta metoda wymaga zwrócenia obiektu VersionInfo. Poniższy przykład pokazuje, możesz przekonwertować wersję ciągu tekstowego pakietu SDK na wersję 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 powinna zostać zwrócona wersja adaptera. Ta wersja jest przekazywana do licytującego w ramach żądania OpenRTB.

Oprogramowanie open source i wersje Google adaptery użyj 4-cyfrowego schematu wersji adaptera, a VersionInfo zezwala tylko na 3 cyfr. Aby to obejść, najlepiej połączyć ostatnie 2 cyfry do wersji 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()

Limit czasu: 30 sekund

Metoda initialize() to pierwsza metoda wywoływana przez adapter. Jest tylko raz na sesję. Ta metoda umożliwia uzyskanie listy MediationConfiguration obiekty, które reprezentują pełną listę miejsc docelowych w tej aplikacji skonfigurowanych pod kątem sieci reklamowej; Możesz odtwarzać treści w pętli za pomocą tej listy, aby przeanalizować dane logowania do każdego miejsca docelowego, i przekazywać odpowiednie dane do pakietu SDK do zainicjowania.

Gdy pakiet SDK zostanie zainicjowany i będzie gotowy do odbierania żądań reklamy, wywołaj Metoda onInitializationSucceeded() InitializationCompleteCallback. To wywołanie zwrotne jest przekazywane do wydawców aplikacji, aby wiedzieli, że może zacząć wczytywać reklamy.

Uwaga: metoda initialize() jest wywoływana w przypadku zbędnych instancji adaptera. Żadne inne metody nie będą wywoływane dla tej konkretnej instancji. Jeśli ładowarka musi zapisać stan w wyniku tej metody, każdy stan powinien 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()

Limit czasu: 1 sekunda

Za każdym razem, gdy wydawca wysyła żądanie reklamy, tworzone jest nowe wystąpienie elementu RtbAdapter utworzony i wywoływana jest metoda collectSignals(). To wystąpienie Parametr RtbAdapter będzie używany przez cały czas trwania żądania reklamy, odpowiedzi i cykl życia danej reklamy. Metoda collectSignals() umożliwia dostarcza sygnały z urządzenia, które mają być wysyłane do systemu licytującego Żądanie OpenRTB.

Funkcja collectSignals() jest wywoływana w wątku w tle. Pakiet SDK do reklam mobilnych Google jednocześnie prosi o sygnały ze wszystkich adapterów uczestniczą w określaniu stawek. Okaż szacunek i ogranicz wywołania do wątku UI w tym czasie. Ciężka praca, którą musi wykonać adapter lub pakiet SDK, aby zebrać dane. sygnały powinny być wykonywane w metodzie initialize() i w pamięci podręcznej.

Po przygotowaniu sygnałów odwołaj się do wywołania zwrotnego onSuccess() za pomocą zakodowanych sygnałów.

Oto przykładowa implementacja:

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

Jeśli adapter nie rejestruje sygnałów, wywołaj signalCallbacks.onFailure() z tekstem wyjaśniającym, który z nich wystąpił.

Uwaga: ciąg sygnałów może reprezentować dowolny obiekt i znajdować się w dowolnym np. zwykły plik JSON, zakodowany w standardzie Base64 lub innej wyboru. Zalecamy, aby sygnały szyfrowania były nieprzejrzyste poza Twoją siecią.

Wdrażanie metod wczytywania reklam

Czas oczekiwania: 10 sekund

Jeśli licytujący zwróci zwycięską stawkę, pakiet SDK do reklam mobilnych Google używa adaptera, by wczytać zwycięską reklamę, przekazując Ci wszystkie dane system licytujący zwrócił informację, że pakiet SDK musi wczytać tę reklamę.

Dokładna metoda ładowania, która zostanie wywołana, zależy od reklamy format, którego dotyczy to żądanie:

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

Zaimplementuj te metody w formatach reklam obsługiwanych przez adapter.

Metoda wczytywania jest wywoływana w wątku interfejsu użytkownika w tym samym wystąpieniu adaptera, z którego pochodzą sygnały. Metoda ta zapewnia: parametry:

• Identyfikator MediationAdConfiguration zawierający parametry, których potrzebuje pakiet SDK wczytanie reklamy zwycięskiej stawki, np. odpowiedzi na stawkę i wszystkich danych uwierzytelniających wydawcy skonfigurowanym w interfejsie AdMob.

• Obiekt MediationAdLoadCallback używany do powiadamiania pakietu SDK do reklam mobilnych Google po udanym lub nieudanym wczytaniu.

Gdy pakiet SDK wczyta reklamę, wywołaj mediationAdLoadCallback.onSuccess(). W nie udało się wczytać reklamy zdarzenia, wywołaj mediationAdLoadCallback.onFailure() z opisowy błąd, który wystąpił.

Metoda mediationAdLoadCallback.onSuccess() wymaga przesłania atrybutu potwierdzający jej wybór. interfejsów zdefiniowanych przez Google Mobile Pakiet SDK do wyświetlania reklam. Te interfejsy reklam wymagają podania pewnych informacji o reklamie.

MediationAdConfiguration ma też getWatermark() zwraca ciąg zakodowany w standardzie base64 reprezentujący obraz PNG. Ten obraz powinny znaleźć się w przezroczystej nakładce na reklamy. Skontaktuj się z Google, aby uzyskać dodatkowe wskazówki dotyczące renderowania znaku wodnego. Zawiera on metadane dotyczące wyświetlanej reklamy, dzięki którym wydawcy mogą określić, źródło wyświetlanych reklam.

W przypadku banerów poprosimy Cię o podanie widoku banera. W przypadku reklam pełnoekranowych reklam z nagrodą, poprosimy Cię o wdrożenie metody show(), aby wyświetlać reklamę w przyszłości. Zalecamy, aby zajęcia, które czy wczytywanie reklam odpowiada również za implementację tych metod reklamowych.

Oto przykładowa implementacja loadBannerAd(). Pamiętaj że implementacja adaptera będzie wyglądać inaczej, integruje się 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 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;
  }
}

Zdarzenia cyklu życia prezentacji reklamy usługi przekaźnika

Ostatecznym obowiązkiem adaptera jest powiadomienie pakietu SDK do reklam mobilnych Google wszystkich zdarzeń cyklu życia prezentacji, tak aby można było przekazać je do wydawcy. Wydawca oczekuje tych wywołań w określonych momentach – niezależnie od tego, Sieć reklamowa wyświetla reklamę, dlatego ważne jest, aby jak najwięcej z nich wywołania zwrotne są wywoływane możliwie we właściwym czasie, dzięki czemu Pakiet SDK do reklam mobilnych może je przekazać wydawcy.

Adaptery powinny w odpowiednich przypadkach wywoływać te zdarzenia:

Wspólne dla wszystkich formatów
Metoda	Kiedy zadzwonić
reportAdClicked()	Reklama została kliknięta.
reportAdImpression()	Wyświetlono reklamę.
onAdOpened()	Reklama była wyświetlana na pełnym ekranie.
onAdClosed()	Tryb pełnego ekranu 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ął się film w reklamie.
onVideoCompleted()	Film z reklamy został odtworzony.

Przejściówka otrzymuje MediationAdLoadCallback<MediationAdT, MediationAdCallbackT> obiektu po wywołaniu funkcji mediationAdLoadCallback.onSuccess(). Adaptery są dostępne powinien przechowywać ten obiekt i używać go do wywoływania zdarzeń prezentacji które pojawiają się w reklamie.

Zwykle większość z tych zdarzeń jest wywoływana przez pakiet SDK sieci reklamowej. rolą adaptera jest po prostu mapowanie wywołań zwrotnych z pakietu SDK sieci reklamowej pakietu SDK do reklam mobilnych Google.

Poniższy przykład pokazuje, jak można przekierować wywołania zwrotne z pola Odbiornik reklam 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();
        }
    }
});

Zasoby wymagane do śledzenia wyświetleń reklamy natywnej

Pakiet SDK do reklam mobilnych Google rejestruje wyświetlenie reklamy natywnej, gdy reklama jest widoczna. Jeśli Twój pakiet SDK sieci reklamowej wymaga wyświetlania określonych komponentów aby wyświetlenie było prawidłowe, licytujący może wskazać te wymagane. komponentów natywnych w odpowiedzi na stawkę. Pakiet SDK do reklam mobilnych Google sprawdzi, czy sprawdź, czy wymagane zasoby natywne są widoczne przed zarejestrowaniem wyświetlenia.

Zobacz wymagane zasoby natywne dokumentacji dotyczącej więcej informacji o tym, jak określić dodatkowe wymagane komponenty w stawce .

Ważne: wszystkie wyświetlenia wyrenderowane jako nieprawidłowe ze względu na dodatkowe wymagane zasoby natywne będą miały wpływ na współczynnik zdarzeń podlegających rozliczeniu w przypadku danego wydawcy.

Pokaż błędy reklamy

W przypadku formatów pełnoekranowych, np. reklam pełnoekranowych i reklam z nagrodą, Wczytywanie zwrotne wywołania zwrotnego przekażesz implementację MediationInterstitialAd. lub MediationRewardedAd aby pakiet SDK do reklam mobilnych Google mógł zażądać wyświetlenia reklamy przez adapter.

Pakiet SDK do reklam mobilnych Google oczekuje, że jeśli adapter wczyta reklamę, reklama jest gotowa do wyświetlenia, gdy wydawca poprosi o jej wyświetlenie. Oznacza to, że każde wywołanie powinno prowadzić do wyświetlenia.

Może się jednak zdarzyć, że nie będzie można wyświetlić reklamy. Jeśli nie może zostać wyświetlone, wywołaj metodę onAdFailedToShow(). wywołanie zwrotne, aby anulować wyświetlenie.

W tabeli poniżej pokazujemy, jak wywołania zwrotne prezentacji wpływają na rejestrowanie wyświetleń formatów reklam pełnoekranowych:

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

¹ W przypadku niepowodzenia wyświetleń, sieć reklamowa nie płaci za to wyświetlenie, ale wpływa na korektę stawki zdarzeń podlegających rozliczeniu. Zobacz pytanie o stawkę sygnałów, aby uzyskać i informacjami o nich.

Poniższy przykładowy przykład pokazuje cykl życia wczytywania/programu, w którym reklama może spowodować niepowodzenie.

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