Entwicklung des Gebotsadapters

Dieser Leitfaden richtet sich an Werbenetzwerke, die einen Gebotsadapter erstellen möchten, um Echtzeitgebote (RTB) in der Google-Vermittlung zu nutzen. Wenn Sie ein Publisher sind, lesen Sie die Anleitung unter Publisher-Vermittlung.

Ein Gebotsadapter ist der clientseitige Teil der Integration. Über den Adapter kann Ihr Werbenetzwerk-SDK mit dem Google Mobile Ads SDK kommunizieren, um von der Gebotsfunktion ausgelieferte Anzeigen zu laden.

Damit die Gebotseinstellung richtig funktioniert, muss der Adapter die Initialisierung übernehmen, Signale erfassen, Anzeigen laden und Lebenszyklusereignisse von Anzeigen weiterleiten. In diesem Leitfaden zeigen wir Ihnen, wie Ihr Adapter für diese Vorgänge implementiert werden sollte.

Hinweis: Für die Teilnahme an Bidding ist außerdem ein Bieter erforderlich, der auf OpenRTB-Anfragen antworten kann. Eine Anleitung zum Einrichten einer Gebotsfunktion wird in diesem Leitfaden nicht behandelt.

Workflow eines Gebotsadapters

Initialisierung

Im Folgenden sehen Sie einen detaillierten Ablauf des gesamten Lebenszyklus des Anfrage-Antwort-Renderings eines Adapters:

Der Adapter ist für die folgenden Abschnitte des Workflows zuständig:

• Schritte 4 bis 7: Initialisieren Sie den Adapter und rufen Sie das Google Mobile Ads SDK nach Abschluss der Initialisierung zurück.

• Schritte 10 bis 13: Signale aus Ihrem Werbenetzwerk-SDK erfassen, die an Ihren Bieter gesendet werden sollen, um an einer RTB-Anfrage teilzunehmen, und sie an das Google Mobile Ads SDK weiterleiten

• Schritte 18 bis 21: Wenn die Gebotsfunktion das erfolgreiche Gebot zurückgibt, laden Sie die Anzeige entsprechend der Antwort der Gebotsfunktion. Teilen Sie dem Google Mobile Ads SDK nach dem Laden mit, dass die Anzeige geladen wurde.

• Schritt 23 und höher: Während Ihre Anzeige ausgeliefert wird, benachrichtigen Sie das Google Mobile Ads SDK über Impressions- und Klickereignisse sowie über andere Anzeigenereignisse, die während des Lebenszyklus der Präsentation auftreten.

Hinweis :Impressionsereignisse werden vom Google Mobile Ads SDK separat erfasst. Wichtig ist aber auch, dass Sie das Impressionsereignis Ihres Werbenetzwerks weiterleiten, damit wir nach Abweichungen suchen können.

Gebotsadapter implementieren

Wenn Sie einen Gebotsadapter für das Google Mobile Ads SDK erstellen möchten, müssen Sie die abstrakte Klasse RtbAdapter erweitern. In den folgenden Abschnitten werden die einzelnen abstrakten Methoden in RtbAdapter erläutert.

getSDKVersionInfo()

Hier sollten Sie die Version Ihres SDKs zurückgeben. Diese Version wird als Teil der OpenRTB-Anfrage an Ihren Bieter übergeben.

Bei dieser Methode müssen Sie eine VersionInfo zurückgeben. Das folgende Beispiel zeigt, wie Sie die Stringversion Ihres SDKs in einen VersionInfo. umwandeln können.

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

Hier sollten Sie die Version Ihres Adapters zurückgeben. Diese Version wird als Teil der OpenRTB-Anfrage an Ihren Bieter übergeben.

Die Open-Source- und versionierten Adapter von Google verwenden ein vierstelliges Adapterversionsschema, VersionInfo unterstützt jedoch nur drei Ziffern. Zur Umgehung dieses Problems empfiehlt es sich, die letzten beiden Ziffern in der Patchversion zu kombinieren, wie unten dargestellt.

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

Zeitlimit: 30 Sekunden

Die Methode initialize() ist die erste Methode, die in Ihrem Adapter aufgerufen wird. Sie wird nur einmal pro Sitzung aufgerufen. Mit dieser Methode erhalten Sie eine Liste mit MediationConfiguration-Objekten, die die vollständige Liste der Placements in dieser App darstellen, die für Ihr Werbenetzwerk konfiguriert sind. Sie können diese Liste durchlaufen, um die Anmeldedaten für jedes Placement zu parsen und relevante Daten zur Initialisierung an Ihr SDK zu übergeben.

Sobald Ihr SDK initialisiert wurde und Anzeigenanfragen empfangen kann, rufen Sie die Methode onInitializationSucceeded() von InitializationCompleteCallback auf. Dieser Callback wird an die App-Publisher weitergeleitet, damit sie wissen, dass sie mit dem Laden von Anzeigen beginnen können.

Hinweis: Die Methode initialize() wird bei einer Wegwerfinstanz eines Adapters aufgerufen. Für diese Instanz werden keine anderen Methoden aufgerufen. Wenn der Adapter aufgrund dieser Methode den Status speichern muss, sollte jeder Zustand statisch sein.

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

Zeitlimit: 1 Sekunde

Jedes Mal, wenn der Publisher eine Anzeige anfordert, wird eine neue Instanz von RtbAdapter erstellt und die Methode collectSignals() aufgerufen. Diese Instanz von RtbAdapter wird für die Dauer der Anzeigenanfrage, der Antwort und des Renderinglebenszyklus für diese Anzeige verwendet. Mit der Methode collectSignals() kann der Adapter Signale vom Gerät bereitstellen, die in einer OpenRTB-Anfrage an die Gebotsfunktion gesendet werden sollen.

collectSignals() wird in einem Hintergrundthread aufgerufen. Das Google Mobile Ads SDK fordert gleichzeitig Signale von allen Adaptern an, die an Geboten teilnehmen. Seien Sie respektvoll und beschränken Sie die Aufrufe des UI-Threads während dieser Zeit. Alle aufwendigen Arbeiten, die Ihr Adapter oder SDK ausführen muss, um Signale zu erfassen, sollten in der initialize()-Methode erfolgen und im Cache gespeichert werden.

Sobald die Signale bereit sind, rufen Sie den onSuccess()-Callback mit Ihren codierten Signalen auf.

Hier ist ein Beispiel für eine Implementierung:

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

Wenn der Adapter keine Signale erfassen kann, rufen Sie signalCallbacks.onFailure() mit einem String auf, der den aufgetretenen Fehler erläutert.

Hinweis: Der Signalstring kann ein beliebiges Objekt darstellen und in einem beliebigen Format vorliegen, z. B. einfaches JSON, Base64-codiert oder eine andere Verschlüsselungsmethode. Wir empfehlen die Verschlüsselung von Signalen, damit Signale außerhalb Ihres Netzwerks intransparent sind.

Lademethoden für Anzeigen implementieren

Zeitlimit: 10 Sekunden

Wenn die Gebotsfunktion das erfolgreiche Gebot zurückgibt, ruft das Google Mobile Ads SDK Ihren Adapter auf, um die erfolgreiche Anzeige zu laden. Dabei werden alle Daten übergeben, die Ihr Bieter zurückgegeben hat und die Ihr SDK zum Laden dieser Anzeige benötigt.

Die genaue Lademethode hängt vom Anzeigenformat ab, für das diese Anfrage bestimmt ist:

Anzeigenformat	Lademethode
Banner	loadBannerAd()
Interstitial	loadInterstitialAd()
Verfügbar	loadRewardedAd()

Implementieren Sie diese Methoden für die Anzeigenformate, die Ihr Adapter unterstützt.

Die Lademethode wird im UI-Thread auf derselben Instanz des Adapters aufgerufen, von der Sie Signale bereitgestellt haben. Diese Methode bietet die folgenden Parameter:

• Ein MediationAdConfiguration mit Parametern, die Ihr SDK zum Laden der Anzeige für das erfolgreiche Gebot benötigt, z. B. die Gebotsantwort und alle vom Publisher in der AdMob-Benutzeroberfläche konfigurierten Anmeldedaten.

• Ein MediationAdLoadCallback-Objekt, über das das Google Mobile Ads SDK benachrichtigt wird, wenn der Ladevorgang erfolgreich ist oder fehlschlägt.

Sobald Ihr SDK die Anzeige lädt, rufen Sie mediationAdLoadCallback.onSuccess() auf. Wenn das Laden der Anzeige fehlschlägt, rufen Sie mediationAdLoadCallback.onFailure() mit einem String auf, der den aufgetretenen Fehler erläutert.

Für die Methode mediationAdLoadCallback.onSuccess() muss ein Objekt übergeben werden, das einer der im Google Mobile Ads SDK definierten "Ad"-Schnittstellen bestätigt. Bei diesen Anzeigenoberflächen müssen Sie Informationen zur Anzeige angeben.

MediationAdConfiguration verfügt auch über die Methode getWatermark(), um einen base64-codierten String zurückzugeben, der ein PNG-Bild darstellt. Dieses Bild sollte in einem transparenten Overlay über Ihren Anzeigen gekachelt werden. Wenden Sie sich an Google, um weitere Informationen zum Rendern des Wasserzeichens zu erhalten. Es enthält Metadaten zur eingeblendeten Anzeige, damit Publisher die Quelle der eingeblendeten Werbung bestimmen können.

Bei Bannern werden Sie aufgefordert, die Banneransicht anzugeben. Bei Interstitial-Anzeigen und Anzeigen mit Prämie werden Sie aufgefordert, die Methode show() zu implementieren, damit die Anzeige zu einem späteren Zeitpunkt ausgeliefert wird. Als Best Practice empfehlen wir Ihnen, Ihre Klasse, die das Laden der Anzeigen übernimmt, auch für die Implementierung dieser Anzeigenmethoden verantwortlich zu machen.

Im Folgenden finden Sie eine Beispielimplementierung von loadBannerAd(). Die Implementierung Ihres Adapters unterscheidet sich, da er mit einem anderen SDK integriert werden kann.

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

Lebenszyklus-Ereignisse von Anzeigenpräsentationen weiterleiten

Die letzte Aufgabe des Adapters besteht darin, das Google Mobile Ads SDK über alle Lebenszyklusereignisse der Präsentation zu informieren, damit diese an den Publisher weitergeleitet werden können. Der Publisher erwartet diese Callbacks zu bestimmten Zeiten, unabhängig davon, von welchem Werbenetzwerk die Anzeige ausgeliefert wird. Daher ist es wichtig, dass so viele dieser Callbacks wie möglich und zum richtigen Zeitpunkt aufgerufen werden, damit sie vom Google Mobile Ads SDK an den Publisher weitergeleitet werden können.

Adapter sollten gegebenenfalls die folgenden Ereignisse aufrufen:

Für alle Formate geeignet
Methode	Wann Sie anrufen sollten
reportAdClicked()	Auf die Anzeige wurde geklickt.
reportAdImpression()	Die Anzeige hat eine Impression erzielt.
onAdOpened()	Die Anzeige war im Vollbildmodus zu sehen.
onAdClosed()	Die Vollbildansicht der Anzeige wurde geschlossen.
onAdLeftApplication()	Die Anzeige hat den Nutzer veranlasst, die App zu verlassen.
Anzeigen mit Prämie
onRewarded()	Der Nutzer erhält eine Prämie.
Videorückrufe (Anzeigen mit Prämie und native Anzeigen)
onVideoStarted()	Das Video der Anzeige wurde gestartet.
onVideoCompleted()	Das Video der Anzeige wurde beendet.

Der Adapter erhält nach dem Aufrufen von mediationAdLoadCallback.onSuccess() ein MediationAdLoadCallback<MediationAdT, MediationAdCallbackT>-Objekt zurück. Es wird erwartet, dass Adapter dieses Objekt beibehalten und zum Aufrufen von Präsentationsereignissen in Ihrer Anzeige verwenden.

In der Regel werden die meisten dieser Ereignisse durch das SDK Ihres Werbenetzwerks ausgelöst. Die Aufgabe des Adapters besteht darin, die Callbacks von Ihrem Werbenetzwerk-SDK dem Google Mobile Ads SDK zuzuordnen.

Im folgenden Beispiel sehen Sie, wie Sie Callbacks vom Anzeigen-Listener Ihres SDKs an das Google Mobile Ads SDK weiterleiten:

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

Erforderliche Assets für das Impressions-Tracking nativer Anzeigen

Das Google Mobile Ads SDK erfasst eine Impression für eine native Anzeige, wenn 1 px der Anzeige sichtbar ist. Wenn für das SDK Ihres Werbenetzwerks die Anzeige bestimmter Assets erforderlich ist, damit eine gültige Impression gerendert werden kann, kann die Gebotsfunktion diese erforderlichen nativen Assets in der Gebotsantwort angeben. Das Google Mobile Ads SDK prüft dann, ob die erforderlichen nativen Assets angezeigt werden, bevor eine Impression erfasst wird.

Weitere Informationen zum Angeben zusätzlicher erforderlicher Assets in der Gebotsantwort finden Sie in der Dokumentation zu erforderlichen Assets für native Anzeigen.

Wichtiger Hinweis :Alle Impressionen, die aufgrund der zusätzlichen nativen erforderlichen Assets Ihres Werbenetzwerks ungültig werden, wirken sich auf das Verhältnis von abrechenbaren Ereignissen für diesen Publisher aus.

Anzeigenfehler einblenden

Für Vollbildformate wie Interstitial-Anzeigen und Anzeigen mit Prämie stellen Sie im Erfolgslade-Callback eine Implementierung von MediationInterstitialAd oder MediationRewardedAd zur Verfügung, damit das Google Mobile Ads SDK Ihren Adapter zum Ausliefern der Anzeige anfordern kann.

Für das Google Mobile Ads SDK wird davon ausgegangen, dass eine Anzeige nach dem Laden eines Adapters bereit zur Auslieferung ist, wenn der Publisher darum bittet. Das bedeutet, dass jeder Aufruf einer Sendung zu einer Impression führen sollte.

Es gibt jedoch auch Fälle, in denen Sie eine Anzeige nicht präsentieren können. Wenn die Anzeige nicht ausgeliefert werden kann, rufen Sie den Callback onAdFailedToShow() auf, um die Impression abzubrechen.

In der folgenden Tabelle sehen Sie, wie sich Präsentations-Callbacks auf die Aufzeichnung von Impressionen für Vollbildanzeigen auswirken:

Rückruf	Ergebnis
onAdOpened()	Impression recorded
onAdFailedToShow()	Impression failure^1
Einige Sekunden lang keine der oben genannten Optionen	Impression recorded

¹ Fehlgeschlagene Impressionen werden Ihrem Werbenetzwerk nicht in Rechnung gestellt. Dies wirkt sich jedoch auf die Anpassung der abrechnungsfähigen Ereignisrate aus. Weitere Informationen finden Sie unter Signale für Gebotsanfragen.

Das folgende Beispiel zeigt einen Lade-/Show-Lebenszyklus, bei dem ein Aufruf einer Anzeige zu einem Fehler führen kann.

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