Entwicklung von Gebotsadaptern

Diese Anleitung richtet sich an Werbenetzwerke, die einen Bidding-Adapter erstellen möchten, um an Echtzeitauktionen (Real-Time Bidding, RTB) im Rahmen der Google-Vermittlung teilzunehmen. Wenn Sie Publisher sind, lesen Sie die Anleitung zur Publisher-Vermittlung.

Ein Bidding-Adapter ist der clientseitige Teil der Integration. Mit dem Adapter kann das SDK Ihres Werbenetzwerks mit Google Mobile Ads SDK kommunizieren, um Anzeigen zu laden, die von Ihrem Bieter ausgeliefert werden.

Damit Bidding ordnungsgemäß funktioniert, muss Ihr Adapter die Initialisierung, das Erfassen von Signalen, das Laden von Anzeigen und das Weiterleiten von Ereignissen im Lebenszyklus von Anzeigen verarbeiten. In dieser Anleitung erfahren Sie, wie Ihr Adapter implementiert werden sollte, um diese Vorgänge zu verarbeiten.

Hinweis: Für die Teilnahme an Bidding ist auch ein Bieter erforderlich, der auf OpenRTB-Anfragen antworten kann. Eine Anleitung zum Einrichten eines Bieters ist nicht Teil dieser Anleitung.

Workflow eines Bidding-Adapters

Initialisierung

Im Folgenden sehen Sie einen detaillierten Ablauf des gesamten Lebenszyklus von Anfrage, Antwort und Rendering eines Adapters:

Der Adapter ist für die folgenden Teile des Workflows verantwortlich:

• Schritte 4–7: Initialisieren Sie Ihren Adapter und rufen Sie Google Mobile Ads SDK auf, sobald die Initialisierung abgeschlossen ist.

• Schritte 10–13: Erfassen Sie Signale aus dem SDK Ihres Werbenetzwerks, die an Ihren Bieter gesendet werden sollen, um an einer RTB-Anfrage teilzunehmen, und leiten Sie sie an das Google Mobile Ads SDK weiter.

• Schritte 18–21: Wenn Ihr Bieter das höchste Gebot zurückgibt, laden Sie die Anzeige gemäß der Antwort Ihres Bieters. Benachrichtigen Sie nach dem Laden Google Mobile Ads SDK, dass die Anzeige geladen wurde.

• Schritt 23 und später: Während Ihre Anzeige ausgeliefert wird, benachrichtigen Sie das Google Mobile Ads SDK über Impressionen und Klicks sowie über andere Anzeigenereignisse, die während des Lebenszyklus Ihrer Anzeige auftreten.

Hinweis: Google Mobile Ads SDK erfasst Impressionen separat. Es ist jedoch auch wichtig, dass Sie das Impressionenereignis Ihres Werbenetzwerks weiterleiten, damit wir auf Abweichungen prüfen können.

Bidding-Adapter implementieren

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

getSDKVersionInfo()

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

Für diese Methode müssen Sie ein VersionInfo zurückgeben. Im folgenden Beispiel sehen Sie, wie Sie die Stringversion Ihres SDK in ein 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-Adapter von Google mit Versionsverwaltung verwenden ein 4-stelliges Adapternummerierungsschema, aber die VersionInfo lässt nur 3 Ziffern zu. Um dieses Problem zu umgehen, empfiehlt es sich, die letzten beiden Ziffern in der Patchversion zu kombinieren, wie unten gezeigt.

@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. Diese Methode stellt Ihnen eine Liste von MediationConfiguration-Objekten zur Verfügung, 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 ist und Anzeigenanfragen empfangen kann, rufen Sie die Methode onInitializationSucceeded() des 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 für eine temporäre Instanz eines Adapters aufgerufen. Für diese Instanz werden keine anderen Methoden aufgerufen. Wenn Ihr Adapter aufgrund dieser Methode einen Status speichern muss, sollte dieser Status 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 des Lebenszyklus von Anzeigenanfrage, Antwort und Rendering für diese Anzeige verwendet. Mit der Methode collectSignals() kann Ihr Adapter Signale vom Gerät bereitstellen, die in einer OpenRTB-Anfrage an Ihren Bieter gesendet werden.

collectSignals() wird in einem Hintergrundthread aufgerufen. Google Mobile Ads SDK fordert gleichzeitig Signale von allen Adaptern an, die an Bidding teilnehmen. Bitte beschränken Sie die Aufrufe des UI-Threads während dieser Zeit. Alle aufwendigen Aufgaben, die Ihr Adapter oder SDK zum Erfassen von Signalen ausführen muss, sollten in der initialize() Methode ausgeführt und im Cache gespeichert werden.

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

Hier ist eine Beispielimplementierung:

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

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

Hinweis: Der String mit den Signalen kann ein beliebiges Objekt darstellen und in einem beliebigen Format vorliegen, z. B. als einfaches JSON, Base64-codiert oder in einer anderen von Ihnen gewählten Verschlüsselungsform. Es empfiehlt sich, Signale zu verschlüsseln, damit sie außerhalb Ihres Netzwerks nicht sichtbar sind.

Methoden zum Laden von Anzeigen implementieren

Zeitlimit: 10 Sekunden

Wenn Ihr Bieter das höchste Gebot zurückgibt, ruft das Google Mobile Ads SDK Ihren Adapter auf, um die Anzeige mit dem höchsten Gebot 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, die aufgerufen wird, hängt vom Anzeigenformat ab, für das diese Anfrage gilt:

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

Implementieren Sie diese Methoden für die Anzeigenformate, die von Ihrem Adapter unterstützt werden.

Die Lademethode wird im UI-Thread für dieselbe Instanz des Adapters aufgerufen, von der Sie Signale bereitgestellt haben. Diese Methode stellt Ihnen die folgenden Parameter zur Verfügung:

• Eine MediationAdConfiguration, die Parameter enthält, die Ihr SDK zum Laden der Anzeige für das höchste Gebot benötigt, z. B. die Gebotsantwort und alle Anmeldedaten, die der Publisher in der AdMob-Benutzeroberfläche konfiguriert hat.

• Ein -Objekt, mit dem benachrichtigt wird, wenn das Laden erfolgreich war oder fehlgeschlagen ist.MediationAdLoadCallbackGoogle Mobile Ads SDK

Sobald Ihr SDK die Anzeige geladen hat, rufen Sie mediationAdLoadCallback.onSuccess() auf. Wenn das Laden der Anzeige fehlschlägt, rufen Sie mediationAdLoadCallback.onFailure() mit einem String auf, der den aufgetretenen Fehler erklärt.

Für die Methode mediationAdLoadCallback.onSuccess() müssen Sie ein Objekt übergeben, das einer der vom Google Mobile Ads SDK definierten „Ad“-Schnittstellen entspricht. Bei diesen Anzeigenschnittstellen werden Sie aufgefordert, einige Informationen zur Anzeige anzugeben.

MediationAdConfiguration hat auch eine getWatermark() Methode, um einen Base64-codierten String zurückzugeben, der ein PNG-Bild darstellt. Dieses Bild sollte in einem transparenten Overlay auf Ihren Anzeigen platziert werden. Wenden Sie sich an Google, um weitere Informationen zum Rendern des Wasserzeichens zu erhalten. Es enthält Metadaten zur ausgelieferten Anzeige, mit denen Publisher die Quelle der ausgelieferten Anzeigen ermitteln können.

Bei Bannern werden Sie aufgefordert, die Banneransicht anzugeben. Bei Interstitials und Anzeigen mit Prämie werden Sie aufgefordert, eine Methode show() zu implementieren, um die Anzeige zu einem späteren Zeitpunkt auszuliefern. Als Best Practice empfehlen wir, dass die Klasse, die das Laden der Anzeige übernimmt, auch für die Implementierung dieser Anzeigenmethoden verantwortlich ist.

Im Folgenden sehen Sie eine Beispielimplementierung von loadBannerAd(): Beachten Sie, dass die Implementierung Ihres Adapters anders aussieht, da Ihr Adapter in ein anderes SDK eingebunden ist.

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

Ereignisse im Lebenszyklus der Anzeigenauslieferung weiterleiten

Die letzte Aufgabe des Adapters besteht darin, Google Mobile Ads SDK über alle Ereignisse im Lebenszyklus der Anzeigenauslieferung zu benachrichtigen, damit diese an den Publisher weitergeleitet werden können. Der Publisher erwartet diese Callbacks zu bestimmten Zeiten, unabhängig davon, welches Werbenetzwerk die Anzeige ausliefert. Daher ist es wichtig, dass so viele dieser Callbacks wie möglich und zum richtigen Zeitpunkt aufgerufen werden, damit Google Mobile Ads SDK sie an den Publisher weiterleiten kann.

Adapter sollten die folgenden Ereignisse aufrufen, wenn sie zutreffen:

Für alle Formate
Methode	Wann aufrufen?
reportAdClicked()	Auf die Anzeige wurde geklickt.
reportAdImpression()	Die Anzeige hat eine Impression erzielt.
onAdOpened()	Die Anzeige wurde im Vollbildmodus präsentiert.
onAdClosed()	Die Vollbildansicht der Anzeige wurde geschlossen.
onAdLeftApplication()	Die Anzeige hat dazu geführt, dass der Nutzer die App verlassen hat.
Anzeigen mit Prämie
onRewarded()	Der Nutzer erhält eine Prämie.
Video-Callbacks (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. Adapter müssen dieses Objekt beibehalten und damit Ereignisse im Lebenszyklus der Anzeigenauslieferung aufrufen, die für Ihre Anzeige auftreten.

In der Regel werden die meisten dieser Ereignisse vom SDK Ihres Werbenetzwerks ausgelöst. Die Aufgabe des Adapters besteht lediglich darin, die Callbacks aus dem SDK Ihres Werbenetzwerks dem Google Mobile Ads SDKzuzuordnen.

Im folgenden Beispiel sehen Sie, wie Sie Callbacks vom Anzeigenlistener Ihres SDK an Google Mobile Ads SDKweiterleiten:

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 die Impressionenerfassung bei nativen Anzeigen

Google Mobile Ads SDK erfasst eine Impression für eine native Anzeige, wenn 1 Pixel der Anzeige sichtbar ist. Wenn für das SDK Ihres Werbenetzwerks bestimmte Assets angezeigt werden müssen, um eine gültige Impression zu erzielen, kann Ihr Bieter diese erforderlichen nativen Assets in der Gebotsantwort angeben. Google Mobile Ads SDK prüft dann , ob Ihre 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.

**Wichtig**: Alle Impressionen, die aufgrund der zusätzlichen erforderlichen nativen Assets Ihres Werbenetzwerks als ungültig gerendert werden, wirken sich auf das Verhältnis der abrechenbaren Ereignisse für diesen Publisher aus.

Anzeigenfehler anzeigen

Bei Vollbildformaten wie Interstitials und Anzeigen mit Prämie geben Sie im Callback für das erfolgreiche Laden eine Implementierung von MediationInterstitialAd oder MediationRewardedAd an, damit Google Mobile Ads SDK Ihren Adapter auffordern kann, die Anzeige auszuliefern.

Google Mobile Ads SDK geht davon aus, dass eine Anzeige, die von einem Adapter erfolgreich geladen wurde, ausgeliefert werden kann, wenn der Publisher dies anfordert. Das bedeutet, dass jeder Aufruf von „Ausliefern“ zu einer Impression führen sollte.

Es kann jedoch Sonderfälle geben, in denen Sie eine Anzeige nicht ausliefern können. Wenn Sie die Anzeige nicht ausliefern können, rufen Sie den onAdFailedToShow() Callback auf, um die Impression abzubrechen.

In der folgenden Tabelle sehen Sie, wie sich Callbacks im Lebenszyklus der Anzeigenauslieferung auf die Impressionenerfassung für Vollbildanzeigenformate auswirken:

Callback	Ergebnis
onAdOpened()	Impression recorded
onAdFailedToShow()	Impression failure^1
Keine der oben genannten Optionen für mehrere Sekunden	Impression recorded

¹ Bei fehlgeschlagenen Impressionen wird Ihrem Werbenetzwerk die Impression nicht in Rechnung gestellt, aber sie wirkt sich auf die Anpassung der Rate abrechenbarer Ereignisse aus. Weitere Informationen finden Sie unter Signale für Gebotsanfragen.

Das folgende Beispiel zeigt einen Lebenszyklus für Laden/Ausliefern, bei dem ein Aufruf zum Ausliefern 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, ...);
  }
}