Google uses AI technology to translate content into your preferred language. AI translations can contain errors.

Tworzenie adaptera ustalania 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 instrukcjami dotyczącymi mediacji wydawcy.

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

Aby ustalanie stawek działało prawidłowo, adapter musi obsługiwać inicjowanie, zbieranie sygnałów, wczytywanie reklam i przekazywanie zdarzeń cyklu życia reklamy. Z tego przewodnika dowiesz się, jak wdrożyć adapter, aby obsługiwał te operacje.

Proces adaptera ustalania stawek

Zdarzenie inicjujące

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

Adapter jest odpowiedzialny za te części procesu:

Kroki 4–7: zainicjuj adapter i wywołaj Google Mobile Ads SDK po zakończeniu inicjowania.
Kroki 10–13: zbierz sygnały z pakietu SDK sieci reklamowej, aby wysłać je do licytującego w żądaniu RTB, i przekaż je do pakietu SDK do reklam mobilnych Google.
Kroki 18–21: jeśli licytujący zwróci wygrywającą stawkę, wczytaj reklamę zgodnie z odpowiedzią licytującego. Po wczytaniu powiadom Google Mobile Ads SDK, że reklama została wczytana.
Krok 23 i kolejne: gdy reklama się wyświetla, powiadom pakiet SDK do reklam mobilnych Google o wyświetleniach i kliknięciach oraz o innych zdarzeniach reklamowych, które występują podczas cyklu życia reklamy.

Implementowanie adaptera ustalania stawek

Aby utworzyć adapter ustalania stawek dla Google Mobile Ads SDK, 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 zwrócenia VersionInfo. Poniższy przykład pokazuje, jak przekonwertować wersję pakietu SDK w postaci ciągu znaków 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 z numerami wersji używają 4-cyfrowego schematu wersji adaptera, ale VersionInfo pozwala tylko na 3 cyfry. Aby obejść ten problem, 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 wywoływana tylko raz na sesję. Ta metoda udostępnia 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 na potrzeby inicjowania.

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

@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 wysyła żądanie reklamy, tworzona jest nowa instancja RtbAdapter i wywoływana jest metoda collectSignals(). Ta instancja RtbAdapter będzie używana przez cały cykl życia żądania reklamy, odpowiedzi i renderowania. Metoda collectSignals() umożliwia 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. Google Mobile Ads SDK jednocześnie prosi o sygnały wszystkie adaptery uczestniczące w ustalaniu stawek. W tym czasie ogranicz wywołania do wątku UI. Wszelkie złożone zadania, które adapter lub pakiet SDK musi wykonać, aby zebrać sygnały, powinny być wykonywane w metodzie initialize() i zapisywane w pamięci podręcznej.

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

Oto przykładowa implementacja:

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

Jeśli adapter nie może zebrać sygnałów, wywołaj signalCallbacks.onFailure() z ciągiem znaków wyjaśniającym, jaki błąd wystąpił.

Implementowanie metod wczytywania reklam

Czas oczekiwania: 10 sekund

Jeśli licytujący zwróci wygrywającą stawkę, Google Mobile Ads SDK wywoła adapter, aby wczytać wygrywającą reklamę, przekazując wszystkie dane zwrócone przez licytującego, które są potrzebne pakietowi SDK do wczytania tej reklamy.

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

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

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

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

MediationAdConfiguration, który zawiera parametry potrzebne pakietowi SDK do wczytania reklamy z wygrywającą stawką, takie jak odpowiedź na pytanie o stawkę i dane logowania skonfigurowane przez wydawcę w interfejsie AdMob.
Obiekt MediationAdLoadCallback używany do powiadamiania Google Mobile Ads SDK o powodzeniu lub niepowodzeniu wczytywania.

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

Metoda mediationAdLoadCallback.onSuccess() wymaga przekazania obiektu, który jest zgodny z jednym z interfejsów „Ad” zdefiniowanych przez pakiet SDK do reklam mobilnych Google. Te interfejsy reklam wymagają podania pewnych informacji o reklamie.

MediationAdConfiguration ma też metodę getWatermark() , która zwraca ciąg znaków zakodowany w Base64 reprezentujący obraz PNG. Ten obraz powinien być wyświetlany jako przezroczysta nakładka na reklamach. Aby uzyskać dodatkowe wskazówki dotyczące renderowania znaku wodnego, skontaktuj się z Google. Zawiera metadane o wyświetlanej reklamie, które wydawcy mogą wykorzystać do określenia źródła wyświetlanych reklam.

W przypadku banerów poprosimy Cię o podanie widoku banera. W przypadku reklam pełnoekranowych i z nagrodą poprosimy Cię o zaimplementowanie metody show(), aby wyświetlić reklamę w późniejszym czasie. Zalecamy, aby klasa, która wczytuje reklamę, była też 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 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 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 reklamy

Ostatnim obowiązkiem adaptera jest powiadamianie Google Mobile Ads SDK o wszelkich zdarzeniach cyklu życia reklamy, aby można je było przekazać do 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 wywoływać jak najwięcej tych wywołań zwrotnych w odpowiednim czasie, aby Google Mobile Ads SDK mógł je przekazać do wydawcy.

Adaptery powinny wywoływać te zdarzenia, gdy jest to możliwe:

Wspólne dla wszystkich formatów
Metoda	Kiedy wywołać
`reportAdClicked()`	Kliknięto reklamę.
`reportAdImpression()`	Reklama wyrenderowała wyświetlenie.
`onAdOpened()`	Reklama wyświetliła wyświetlenie ekranu w widoku pełnoekranowym.
`onAdClosed()`	Wyświetlenie ekranu reklamy w trybie pełnoekranowym zostało zamknięte.
`onAdLeftApplication()`	Reklama spowodowała, że użytkownik opuścił aplikację.
Reklamy z nagrodą
`onRewarded()`	Użytkownik otrzymał nagrodę.
Wywołania zwrotne wideo (reklamy z nagrodą i natywne)
`onVideoStarted()`	Rozpoczęło się odtwarzanie filmu w reklamie.
`onVideoCompleted()`	Odtwarzanie filmu w reklamie zostało zakończone.

Po wywołaniu 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 reklamie.

Zazwyczaj większość tych zdarzeń jest wywoływana przez pakiet SDK sieci reklamowej. Rola adaptera polega po prostu na mapowaniu wywołań zwrotnych z pakietu SDK sieci reklamowej na Google Mobile Ads SDK.

Poniższy przykład pokazuje, jak przekazywać wywołania zwrotne z odbiornika reklam pakietu SDK do 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();
        }
    }
});

Wymagane komponenty do śledzenia wyświetleń reklam natywnych

Google Mobile Ads SDK rejestruje wyświetlenie reklamy natywnej, gdy widoczny jest 1 piksel reklamy. Jeśli pakiet SDK sieci reklamowej wymaga wyświetlania określonych zasobów, aby wyrenderować prawidłowe wyświetlenie, licytujący może wskazać te wymagane zasoby natywne w odpowiedzi na pytanie o stawkę. Google Mobile Ads SDK następnie sprawdza , czy wymagane komponenty natywne są wyświetlane, zanim zarejestruje wyświetlenie.

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

Wyświetlanie błędów reklam

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

Google Mobile Ads SDK oczekuje, że jeśli adapter wczyta reklamę, będzie ona gotowa do wyświetlenia, gdy wydawca poprosi o jej wyświetlenie. Oznacza to, że każde wywołanie wyświetlenia powinno skutkować wyświetleniem.

Mogą jednak wystąpić sytuacje, w których nie można wyświetlić reklamy. Jeśli nie możesz wyświetlić reklamy, wywołaj onAdFailedToShow() wywołanie zwrotne, aby anulować wyświetlenie.

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

Wywołanie zwrotne	Wynik
onAdOpened()	`Impression recorded`
onAdFailedToShow()	`Impression failure¹`
Żadne 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 dostosowanie stawek współczynnika zdarzeń podlegających rozliczeniu. Więcej informacji znajdziesz w sekcji Sygnały pytania o stawkę.

Poniższy przykładowy kod 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, ...);
  }
}