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 (RTB) w ramach zapośredniczenia Google. Jeśli jesteś wydawcą, zapoznaj się z instrukcjami dotyczącymi zapośredniczenia wydawcy.

Adapter do określania stawek to część integracji po stronie klienta. Adapter umożliwia pakietowi SDK sieci reklamowej komunikowanie się z usługą Google Mobile Ads SDK (Legacy) 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ń cyklu życia reklamy. W tym przewodniku pokażemy, jak zaimplementować adapter, aby obsługiwał te operacje.

Przepływ pracy adaptera do określania stawek

Zdarzenie inicjujące

Poniżej znajdziesz szczegółowy opis całego cyklu życia adaptera, od żądania przez odpowiedź po renderowanie:

Adapter odpowiada za te części przepływu pracy:

• Kroki 4–7. Zainicjuj adapter i wywołaj Google Mobile Ads SDK (Legacy) po zakończeniu inicjowania.

• Kroki 10–13. Zbierz sygnały z pakietu SDK sieci reklamowej, które mają zostać wysłane do licytującego, aby mógł on uczestniczyć 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 Google Mobile Ads SDK (Legacy), że reklama została wczytana.

• Krok 23 i kolejne: podczas wyświetlania reklamy powiadamiaj pakiet SDK do reklam mobilnych Google o zdarzeniach wyświetlenia i zdarzeniach kliknięcia oraz o innych zdarzeniach reklamowych, które występują podczas cyklu życia prezentacji reklamy.

Implementowanie adaptera do określania stawek

Aby utworzyć adapter do określania stawek dla Google Mobile Ads SDK (Legacy), musisz rozszerzyć klasę abstrakcyjną RtbAdapter. W sekcjach poniżej opisano każdą metodę abstrakcyjną w RtbAdapter.

getSDKVersionInfo()

Tutaj należy podać wersję pakietu SDK. Ta wersja jest przekazywana do licytującego w ramach żądania OpenRTB.

Ta metoda wymaga zwrócenia wartości VersionInfo. Poniższy przykład pokazuje, jak przekonwertować wersję ciągu znaków 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()

Tutaj należy zwrócić wersję adaptera. Ta wersja jest przekazywana licytującemu w ramach żądania OpenRTB.

Adaptery open source i wersjonowane Google używają 4-cyfrowego schematu wersji, ale VersionInfo zezwala tylko na 3 cyfry. Aby obejść ten problem, zalecamy połączenie ostatnich 2 cyfr w wersji poprawek, 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() 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 przejrzeć tę listę, aby przeanalizować dane logowania dla każdego miejsca docelowego i przekazać odpowiednie dane do pakietu SDK w celu inicjalizacji.

Gdy pakiet SDK zostanie zainicjowany i będzie gotowy do odbierania żądań reklamy, wywołaj metodę onInitializationSucceeded() obiektu InitializationCompleteCallback. To wywołanie zwrotne jest przekazywane do wydawców aplikacji, aby wiedzieli, ż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()

Limit czasu: 1 sekunda

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

Funkcja collectSignals() jest wywoływana w wątku w tle. Google Mobile Ads SDK (Legacy) jednocześnie prosi o sygnały ze wszystkich adapterów uczestniczących w określaniu stawek. W tym czasie należy ograniczyć wywołania wątku UI. Wszelkie wymagające dużej mocy obliczeniowej działania, 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ładowy kod:

@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 błąd, który wystąpił.

Wdrażanie metod wczytywania reklam

Limit czasu: 10 sekund

Jeśli Twój system licytujący zwróci zwycięską stawkę, Google Mobile Ads SDK (Legacy) wywoła Twój adapter, aby wczytać zwycięską reklamę, i przekaże Ci wszystkie dane zwrócone przez system licytujący, których Twój pakiet SDK potrzebuje do wczytania tej reklamy.

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

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

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

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

• Obiekt MediationAdLoadCallback używany do powiadamiania Google Mobile Ads SDK (Legacy) o powodzeniu lub niepowodzeniu wczytywania.

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

Metoda mediationAdLoadCallback.onSuccess() wymaga przekazania obiektu, który potwierdza jeden z interfejsów „Reklama” zdefiniowanych przez pakiet SDK do reklam mobilnych Google. W tych interfejsach musisz podać pewne informacje 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 formie kafelków w przezroczystej nakładce na reklamy. Skontaktuj się z Google, aby uzyskać dodatkowe wskazówki dotyczące renderowania znaku wodnego. Zawiera metadane dotyczące wyświetlanej reklamy, 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 reklam z nagrodą musisz zaimplementować metodę show(), aby wyświetlić reklamę w późniejszym czasie. Zalecamy, aby klasa, która wczytuje reklamy, była też odpowiedzialna za implementację tych metod reklamowych.

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 (Legacy).
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

Ostatnim zadaniem adaptera jest powiadamianie Google Mobile Ads SDK (Legacy) o wszystkich zdarzeniach cyklu życia prezentacji, aby można je było przekazać 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 we właściwym czasie, aby usługa Google Mobile Ads SDK (Legacy) mogła je przekazywać wydawcy.

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

Po wywołaniu mediationAdLoadCallback.onSuccess() adapter otrzymuje obiekt MediationAdLoadCallback<MediationAdT, MediationAdCallbackT>. Adaptery powinny przechowywać ten obiekt i używać go do wywoływania zdarzeń prezentacji, 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 (Legacy).

Poniższy przykład pokazuje, jak przekazywać wywołania zwrotne z detektora reklam pakietu SDK do Google Mobile Ads SDK (Legacy):

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

Komponenty wymagane do śledzenia wyświetleń reklam natywnych

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

Więcej informacji o tym, jak określać w odpowiedzi na pytanie o stawkę dodatkowe wymagane komponenty, 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 reklamy z nagrodą, w wywołaniu zwrotnym po udanym wczytaniu podaj implementację MediationInterstitialAd lub MediationRewardedAd, aby pakiet Google Mobile Ads SDK (Legacy) mógł poprosić adapter o wyświetlenie reklamy.

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

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

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

¹ 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 w pytaniach o stawkę.

Poniższy przykład pokazuje cykl życia wczytywania/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, ...);
  }
}