Ta strona została przetłumaczona przez Cloud Translation API.

Tworzenie adaptera ustalania stawek

Ten przewodnik jest przeznaczony dla sieci reklamowych, które chcą tworzyć adaptery ustalania stawek, aby brać udział w określaniu stawek w czasie rzeczywistym (RTB) w ramach zapośredniczenia Google. Jeśli jesteś wydawcą, zapoznaj się z instrukcjami dotyczącymi pośrednictwa.

Adapter ustalania stawek to część integracji po stronie klienta. Umożliwia on pakietowi SDK sieci reklamowej komunikowanie się z pakietem SDK do reklam mobilnych Google w celu wczytywania reklam wyświetlanych przez licytującego.

Aby określanie 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 opiszemy, jak zaimplementować adapter do obsługi tych operacji.

Proces działania adaptera ustalania stawek

Zdarzenie inicjujące

Poniżej przedstawiamy szczegółowy przepływ całego cyklu życia adaptera od żądania do odpowiedzi i wyświetlenia:

Adapter odpowiada za te części procesu:

Kroki 4–7. Po zakończeniu inicjalizacji zainicjuj adapter i wywołaj pakiet SDK do reklam mobilnych Google.
Kroki 10–13. Zbieraj sygnały z pakietu SDK sieci reklamowej, aby wysyłać je do oferenta w ramach żądania RTB, i przesyłaj je do pakietu SDK do reklam mobilnych Google.
Kroki 18–21. Jeśli licytujący zwróci zwycięską stawkę, wyświetl reklamę zgodnie z odpowiedzią licytującego. Po załadowaniu powiadomi pakiet SDK do reklam mobilnych Google o załadowaniu reklamy.
Krok 23 i później: podczas wyświetlania reklamy informuj pakiet SDK do reklam mobilnych Google o zdarzeniach wyświetlenia i kliknięcia, a także o innych zdarzeniach reklamy, które występują w trakcie jej cyklu życia.

Wdrażanie adaptera ustalania stawek

Aby utworzyć adapter określania stawek dla pakietu SDK do reklam mobilnych Google, musisz rozszerzyć abstrakcyjną klasę RtbAdapter. W sekcjach poniżej opisano każdą abstrakcyjną metodę w RtbAdapter.

getSDKVersionInfo()

Tutaj powinieneś podać wersję pakietu SDK. Ta wersja jest przekazywana licytującemu w ramach żądania OpenRTB.

Ta metoda wymaga zwrócenia VersionInfo. Przykład poniżej pokazuje, jak możesz przekonwertować wersję ciągu w pakiecie 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()

Tutaj powinieneś podać wersję adaptera. Ta wersja jest przekazywana licytującemu w ramach żądania OpenRTB.

Karta graficzna Google z otwartym kodem źródłowym i wersją używa 4-cyfrowego schematu wersji karty graficznej, ale VersionInfo obsługuje tylko 3 cyfry. Aby tego uniknąć, zalecamy połączenie ostatnich 2 cyfr z 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 Twoim adapterze. Jest wywoływany tylko raz na sesję. Ta metoda udostępnia listę obiektów MediationConfiguration, która zawiera pełną listę dostępnych w aplikacji miejsc docelowych skonfigurowanych pod kątem Twojej sieci reklamowej. Możesz przejrzeć tę listę, aby przeanalizować dane logowania dla każdego miejsca docelowego, a następnie przekazać odpowiednie dane do pakietu SDK na potrzeby jego inicjowania.

Gdy pakiet SDK zostanie zainicjowany i będzie gotowy do odbierania żądań reklam, wywołaj metodę onInitializationSucceeded() klasy InitializationCompleteCallback. Ten wywołanie zwrotne jest przekazywane wydawcom aplikacji, aby mogli oni rozpocząć wczytywanie reklam.

@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 żąda reklamy, tworzony jest nowy egzemplarz klasy RtbAdapter i wywoływana jest metoda collectSignals(). Ten egzemplarz RtbAdapter będzie używany przez cały czas trwania żądania reklamy, odpowiedzi i cyklu renderowania tej reklamy. Metoda collectSignals() umożliwia adapterowi dostarczanie sygnałów z urządzenia do kupującego w ramach żądania OpenRTB.

Funkcja collectSignals() jest wywoływana w wątku w tle. Pakiet SDK do reklam mobilnych Google wysyła jednocześnie żądania sygnałów ze wszystkich adapterów uczestniczących w określaniu stawek. Prosimy o kulturę i o ograniczenie wywołań w tym czasie do wątku dotyczącego interfejsu. Wszystkie intensywne działania, które musi wykonać adapter lub pakiet SDK, aby zbierać sygnały, powinny być wykonywane w ramach metody initialize() i przechowywane w pamięci podręcznej.

Gdy sygnały są gotowe, wywołaj funkcję onSuccess() 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 uda się zebrać sygnałów, wywołaj funkcję signalCallbacks.onFailure() z ciągiem wyjaśniającym błąd.

Wdrażanie metod wczytywania reklam

Czas oczekiwania: 10 sekund

Jeśli licytujący zwróci zwycięską stawkę, pakiet SDK do reklam mobilnych Google wywoła Twój adapter, aby załadować zwycięską reklamę, przekazując mu wszystkie dane z licytującego, których potrzebuje pakiet SDK do załadowania tej reklamy.

Dokładna metoda wczytywania zależy od formatu reklamy, do której odnosi się to żądanie:

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

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

Metoda load jest wywoływana w wątku interfejsu użytkownika w tej samej instancji adaptera, z którego pochodzą sygnały. Ta metoda udostępnia te parametry:

MediationAdConfiguration, który zawiera parametry potrzebne pakietowi SDK do załadowania reklamy dla zwycięskiej stawki, np. odpowiedź na stawkę i dane logowania wydawcy skonfigurowane w interfejsie AdMob.
Obiekt MediationAdLoadCallback służy do powiadamiania pakietu SDK do reklam mobilnych Google o skutku wczytywania (udanym lub nieudanym).

Gdy pakiet SDK wczyta reklamę, wywołaj funkcję mediationAdLoadCallback.onSuccess(). Jeśli wczytywanie reklamy się nie powiedzie, wywołaj funkcję mediationAdLoadCallback.onFailure(), podając ciąg znaków wyjaśniający błąd.

Metoda mediationAdLoadCallback.onSuccess() wymaga przekazania obiektu, który potwierdza jeden z interfejsów „Ad” zdefiniowanych przez pakiet SDK do reklam mobilnych Google. Te interfejsy reklam proszą o podanie pewnych informacji o reklamie.

Obiekt MediationAdConfiguration ma też metodę getWatermark(), która zwraca ciąg tekstowy z kodowaniem base64 reprezentujący obraz PNG. Ten obraz powinien być układany w siatkę w przezroczystej nakładce w reklamach. Aby uzyskać dodatkowe wskazówki dotyczące renderowania znaku wodnego, skontaktuj się z Google. Zawiera metadane reklamy wyświetlanej na potrzeby wydawców, którzy mogą na ich podstawie określić źródło wyświetlanych reklam.

W przypadku banerów pojawi się prośba o podanie widoku banera. W przypadku reklam pełnoekranowych i reklam z nagrodą musisz zaimplementować metodę show(), aby wyświetlać reklamy w późniejszym terminie. Zgodnie ze sprawdzoną metodą klasa, która ładuje reklamy, powinna też być odpowiedzialna za implementowanie tych metod reklam.

Poniżej znajdziesz przykładową implementację loadBannerAd(). Pamiętaj, że implementacja 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 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;
  }
}

Przekazywanie zdarzeń cyklu życia prezentacji reklamy

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

W razie potrzeby adaptery powinny wywoływać te zdarzenia:

Wspólne dla wszystkich formatów
Metoda	Kiedy zadzwonić
`reportAdClicked()`	Reklama została kliknięta.
`reportAdImpression()`	Reklama została wyświetlona.
`onAdOpened()`	Reklama była wyświetlana na pełnym ekranie.
`onAdClosed()`	Zamknięto widok pełnoekranowy reklamy.
`onAdLeftApplication()`	Reklama spowodowała, że użytkownik opuścił aplikację.
Reklamy z nagrodą
`onRewarded()`	Użytkownik otrzymuje nagrodę.
wywołania zwrotne dotyczące filmów (reklam wideo z nagrodą i reklam natywnych),
`onVideoStarted()`	Rozpoczęło się odtwarzanie filmu reklamy.
`onVideoCompleted()`	Film reklamy został do końca odtworzony.

Po wywołaniu mediationAdLoadCallback.onSuccess() adapter otrzyma obiekt MediationAdLoadCallback<MediationAdT, MediationAdCallbackT>. Adaptery powinny przechowywać ten obiekt i wykorzystywać go do wywoływania zdarzeń prezentacji występujących w reklamie.

Zwykle większość z nich jest wywoływana przez pakiet SDK sieci reklamowej. Rolą adaptera jest mapowanie wywołań zwrotnych z pakietu SDK sieci reklamowej na pakiet SDK do reklam mobilnych Google.

Ten przykład pokazuje, jak przekazywać wywołania zwrotne z interfejsu ad listener pakietu 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 jest widoczny 1 piksel reklamy. Jeśli pakiet SDK sieci reklamowej wymaga wyświetlania określonych komponentów, aby renderować prawidłowe wyświetlenie, licytujący może wskazać te wymagane komponenty natywnych reklam w odpowiedzi na stawkę. Następnie pakiet SDK do reklam mobilnych Google sprawdza, 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 zapytanie o cenę, znajdziesz w dokumentacji dotyczącej komponentów wymaganych do kreacji natywnych.

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 success pakietu SDK do reklam mobilnych Google należy zaimplementować metodę MediationInterstitialAd lub MediationRewardedAd, aby pakiet SDK do reklam mobilnych Google mógł poprosić adapter o wyświetlenie reklamy.

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

Mogą jednak wystąpić wyjątkowe przypadki, w których nie będziesz mieć możliwości wyświetlenia reklamy. Jeśli nie możesz wyświetlić reklamy, wywołaj funkcję onAdFailedToShow() callback, aby anulować wyświetlenie.

W tabeli poniżej widać, jak wywołania zwrotne dotyczące wyświetlania wpływają na rejestrowanie wyświetleń w przypadku formatów reklam pełnoekranowych:

Oddzwanianie	Wynik
onAdOpened()	`Impression recorded`
onAdFailedToShow()	`Impression failure¹`
Żadna z tych odpowiedzi przez kilka sekund	`Impression recorded`

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

Ten przykładowy przykład pokazuje cykl wczytywania i wyświetlania, w którym wywołanie wyświetlania 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, ...);
  }
}