Dieser Leitfaden richtet sich an Werbenetzwerke, die einen Gebotsadapter erstellen möchten, um an Echtzeitgeboten (Real-Time Bidding, RTB) in der Google-Vermittlung teilzunehmen. Wenn Sie ein Publisher sind, lesen Sie die Anleitung zur Publisher-Vermittlung.
Ein Gebotsadapter ist der clientseitige Teil der Integration. Der Adapter ermöglicht es dem SDK Ihres Werbenetzwerks, mit Google Mobile Ads SDK (Legacy) zu kommunizieren, um von Ihrem Bieter bereitgestellte Anzeigen zu laden.
Damit Bidding ordnungsgemäß funktioniert, muss Ihr Adapter die Initialisierung, das Erfassen von Signalen, das Laden von Anzeigen und das Weiterleiten von Ereignissen im Anzeigenlebenszyklus übernehmen. In diesem Leitfaden wird beschrieben, wie Sie Ihren Adapter implementieren, um diese Vorgänge zu verarbeiten.
Workflow eines Gebotsadapters
Initialisierung
Im Folgenden finden Sie einen detaillierten Ablauf des gesamten Anfrage-Antwort-Rendering-Lebenszyklus eines Adapters:
Der Adapter ist für die folgenden Teile des Workflows verantwortlich:
Schritte 4–7: Initialisieren Sie den Adapter und rufen Sie Google Mobile Ads SDK (Legacy) zurück, sobald die Initialisierung abgeschlossen ist.
Schritte 10–13: Signale vom SDK Ihres Werbenetzwerks erfassen, die an Ihren Bieter gesendet werden sollen, um an einer RTB-Anfrage teilzunehmen, und diese an das Google Mobile Ads SDK weiterleiten.
Schritte 18–21: Wenn Ihre Gebotsfunktion das Gewinnergebot zurückgibt, laden Sie die Anzeige gemäß der Antwort Ihrer Gebotsfunktion. Benachrichtigen Sie Google Mobile Ads SDK (Legacy) nach dem Laden, dass die Anzeige geladen wurde.
Schritt 23 und höher: Während Ihre Anzeige ausgeliefert wird, müssen Sie das Google Mobile Ads SDK über Impressions- und Klick-Ereignisse sowie über andere Anzeigenereignisse informieren, die während des Präsentationslebenszyklus Ihrer Anzeige auftreten.
Bidding-Adapter implementieren
Wenn Sie einen Bidding-Adapter für Google Mobile Ads SDK (Legacy) 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 im Rahmen der OpenRTB-Anfrage an Ihren Bieter übergeben.
Bei dieser Methode müssen Sie ein VersionInfo zurückgeben. Im folgenden Beispiel sehen Sie, wie Sie die Stringversion Ihres SDK in einen VersionInfo. konvertieren 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 im Rahmen der OpenRTB-Anfrage an Ihren Bieter übergeben.
Die Open-Source- und versionierten Adapter von Google verwenden ein vierstelliges Adapterversionsschema, aber das VersionInfo lässt nur drei Stellen zu. Zur Umgehung dieses Problems wird empfohlen, die letzten beiden Ziffern in der Patch-Version 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 liefert eine Liste von 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 das SDK initialisiert ist 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.
@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 der Anzeigenanfrage, der Antwort und des Renderings 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 (Legacy)
fordert gleichzeitig Signale von allen Adaptern an, die am Bidding teilnehmen. Bitte beschränken Sie die Aufrufe des UI-Threads während dieser Zeit. Alle rechenintensiven Aufgaben, die Ihr Adapter oder SDK zum Erfassen von Signalen ausführen muss, sollten in der Methode initialize() ausgeführt und im Cache gespeichert werden.
Sobald die Signale bereit sind, rufen Sie den Callback onSuccess() mit den codierten Signalen auf.
Hier ein Implementierungsbeispiel:
@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 beschreibt.
Methoden zum Laden von Anzeigen implementieren
Zeitlimit: 10 Sekunden
Wenn Ihr Bieter das Gewinnergebot abgibt, ruft die Google Mobile Ads SDK (Legacy) Ihren Adapter auf, um die Gewinneranzeige zu laden. Dabei werden alle Daten übergeben, die Ihr Bieter zurückgegeben hat und die Ihr SDK zum Laden dieser Anzeige benötigt.
Welche Lademethode genau aufgerufen wird, hängt vom Anzeigenformat ab, für das die Anfrage gestellt wird:
| Anzeigenformat | Lademethode |
|---|---|
| Banner | loadBannerAd()
|
| Interstitial | loadInterstitialAd()
|
| Verfügbar | loadRewardedAd()
|
Implementieren Sie diese Methoden für die Anzeigenformate, die Ihr Adapter unterstützt.
Die Methode „load“ wird im UI-Thread auf derselben Instanz des Adapters aufgerufen, von der Sie Signale bereitgestellt haben. Diese Methode bietet die folgenden Parameter:
Ein
MediationAdConfiguration, das Parameter enthält, die Ihr SDK zum Laden der Anzeige für das Gewinnergebot benötigt, z. B. die Gebotsantwort und alle Anmeldedaten, die der Publisher in der AdMob-Benutzeroberfläche konfiguriert hat.Ein
MediationAdLoadCallback-Objekt, mit dem Google Mobile Ads SDK (Legacy) benachrichtigt wird, wenn das Laden erfolgreich ist oder fehlschlägt.
Sobald die Anzeige über das SDK geladen wurde, rufen Sie mediationAdLoadCallback.onSuccess() auf. Wenn das Laden der Anzeige fehlschlägt, rufen Sie mediationAdLoadCallback.onFailure() mit einem String auf, der den aufgetretenen Fehler beschreibt.
Für die Methode mediationAdLoadCallback.onSuccess() müssen Sie ein Objekt übergeben, das einer der vom Google Mobile Ads SDK definierten „Ad“-Schnittstellen entspricht. In diesen Anzeigenoberflächen werden Sie aufgefordert, einige Informationen zur Anzeige anzugeben.
MediationAdConfiguration hat auch eine getWatermark()-Methode, die einen base64-codierten String zurückgibt, der ein PNG-Bild darstellt. Dieses Bild sollte als transparentes Overlay auf Ihren Anzeigen gekachelt werden.
Wenden Sie sich an Google, um weitere Informationen zum Rendern des Wasserzeichens zu erhalten.
Sie enthält Metadaten zur angezeigten Anzeige, die von Publishern verwendet werden, um die Quelle der angezeigten Anzeigen zu ermitteln.
Bei Bannern werden Sie aufgefordert, die Banneransicht anzugeben. Bei Interstitial-Anzeigen und Anzeigen mit Prämie werden Sie aufgefordert, eine show()-Methode zu implementieren, um die Anzeige zu einem späteren Zeitpunkt einzublenden. Als Best Practice empfehlen wir, die Klasse, die die Anzeige lädt, auch für die Implementierung dieser Anzeigenmethoden zu verwenden.
Im Folgenden finden Sie eine Beispielimplementierung von loadBannerAd(). Beachten Sie, dass die Implementierung Ihres Adapters anders aussieht, da er in ein anderes SDK eingebunden wird.
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;
}
}
Lifecycle-Events für die Anzeigenpräsentation weiterleiten
Die letzte Aufgabe des Adapters besteht darin, Google Mobile Ads SDK (Legacy) über alle Präsentations-Lifecycle-Events zu benachrichtigen, damit sie 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 (Legacy) sie an den Publisher weiterleiten kann.
Adapter sollten gegebenenfalls die folgenden Ereignisse aufrufen:
| Für alle Formate gleich | |
|---|---|
| Methode | Aufrufzeitpunkt |
reportAdClicked()
|
Die Anzeige wurde angeklickt. |
reportAdImpression()
|
Die Anzeige hat eine Impression generiert. |
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 vollständig wiedergegeben. |
Der Adapter erhält beim Aufruf von mediationAdLoadCallback.onSuccess() ein MediationAdLoadCallback<MediationAdT, MediationAdCallbackT>-Objekt zurück. Adapter müssen dieses Objekt beibehalten und damit Präsentationsereignisse aufrufen, die in Ihrer Anzeige auftreten.
In der Regel werden die meisten dieser Ereignisse vom SDK Ihres Werbenetzwerks gesteuert. Die Rolle des Adapters besteht lediglich darin, die Callbacks aus dem SDK Ihres Werbenetzwerks dem Google Mobile Ads SDK (Legacy) zuzuordnen.
Das folgende Beispiel zeigt, wie Sie Callbacks vom Anzeigen-Listener Ihres SDKs an Google Mobile Ads SDK (Legacy) 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 Tracking von Impressionen nativer Anzeigen
Google Mobile Ads SDK (Legacy) erfasst eine Impression für eine native Anzeige, wenn 1 Pixel der Anzeige sichtbar ist. Wenn das SDK Ihres Werbenetzwerks bestimmte Assets erfordert, um eine gültige Impression zu rendern, kann Ihr Bieter diese erforderlichen nativen Assets in der Gebotsantwort angeben. Google Mobile Ads SDK (Legacy) prüft dann, ob die erforderlichen nativen Assets angezeigt werden, bevor eine Impression erfasst wird.
Weitere Informationen dazu, wie Sie zusätzliche erforderliche Assets in der Gebotsantwort angeben, finden Sie in der Dokumentation zu erforderlichen Assets für native Anzeigen.
Anzeigenfehler einblenden
Bei Vollbildformaten wie Interstitial-Anzeigen und Anzeigen mit Prämie stellen Sie im Callback für erfolgreiches Laden eine Implementierung von MediationInterstitialAd oder MediationRewardedAd bereit, damit Google Mobile Ads SDK (Legacy) den Adapter auffordern kann, die Anzeige einzublenden.
Google Mobile Ads SDK (Legacy) geht davon aus, dass eine Anzeige, die von einem Adapter geladen wurde, bereit ist, ausgeliefert zu werden, wenn der Publisher sie anfordert. Das bedeutet, dass jeder Aufruf von „show“ zu einer Impression führen sollte.
Es kann jedoch Grenzfälle geben, in denen Sie keine Anzeige einblenden können. Wenn Sie die Anzeige nicht einblenden können, rufen Sie den Callback onAdFailedToShow() auf, um die Impression abzubrechen.
In der folgenden Tabelle sehen Sie, wie sich Präsentations-Callbacks auf die Erfassung von Impressionen für Vollbildanzeigenformate auswirken:
| Rückruf | Ergebnis |
|---|---|
| onAdOpened() | Impression recorded
|
| onAdFailedToShow() | Impression failure1
|
| Keine der genannten Optionen für mehrere Sekunden | Impression recorded
|
1 Bei fehlgeschlagenen Impressionen wird Ihrem Werbenetzwerk die Impression nicht in Rechnung gestellt, aber sie wirkt sich auf die Anpassung der Rate für abrechenbare Ereignisse aus. Weitere Informationen finden Sie unter Signale für Gebotsanfragen.
Das folgende Beispiel zeigt einen Lebenszyklus für das Laden/Anzeigen, bei dem ein Aufruf zum Anzeigen einer Anzeige fehlschlagen 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, ...);
}
}