Dieser Leitfaden richtet sich an Werbenetzwerke, die einen Gebotsadapter erstellen möchten, um an Echtzeitgeboten (Real-Time Bidding, RTB) im Rahmen der Google-Mediation teilzunehmen. Wenn Sie Publisher sind, lesen Sie die Anleitung zur Vermittlung für Publisher.
Ein Gebotsadapter ist der clientseitige Teil der Integration. Mit dem Adapter kann das SDK Ihres Anzeigennetzwerks mit dem Google Mobile Ads SDK kommunizieren, um von Ihrem Bieter bereitgestellte Anzeigen zu laden.
Damit das Bidding richtig funktioniert, muss Ihr Adapter die Initialisierung, das Erfassen von Signalen, das Laden von Anzeigen und das Weiterleiten von Ereignissen im Anzeigenlebenszyklus verarbeiten. In diesem Leitfaden erfahren Sie, wie Ihr Adapter implementiert werden sollte, um diese Vorgänge zu verarbeiten.
Workflow eines Gebotsadapters
Initialisierung
Unten sehen Sie einen detaillierten Ablauf des gesamten Anfrage-, Antwort- und Rendering-Lebenszyklus eines Adapters:
Der Adapter ist für die folgenden Teile des Workflows verantwortlich:
Schritte 4 bis 7: Initialisieren Sie Ihren Adapter und rufen Sie das Google Mobile Ads SDK zurück, sobald die Initialisierung abgeschlossen ist.
Schritte 10 bis 13: Erfassen Sie Signale aus dem SDK Ihres Werbenetzwerks, die an Ihren Bidder gesendet werden sollen, um an einer RTB-Anfrage teilzunehmen, und leiten Sie sie an das Google Mobile Ads SDK weiter.
Schritte 18 bis 21: Wenn Ihre Gebotsfunktion das Gewinnergebot zurückgibt, laden Sie die Anzeige entsprechend der Antwort Ihrer Gebotsfunktion. Benachrichtigen Sie das Google Mobile Ads SDK, dass die Anzeige geladen wurde.
Schritt 23 und später: Benachrichtigen Sie das Google Mobile Ads SDK während der Anzeigenschaltung über Impressions- und Klickereignisse sowie über die anderen Anzeigenereignisse, die während des Präsentationslebenszyklus Ihrer Anzeige auftreten.
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 wird jede abstrakte Methode 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 eine VersionInfo zurückgeben. Im folgenden Beispiel sehen Sie, wie Sie die String-Version des SDK in ein 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-Adapter von Google mit Versionsverwaltung verwenden ein 4-stelliges Adapternummerierungsschema, VersionInfo lässt jedoch nur 3 Ziffern zu. Um dieses Problem zu umgehen, wird empfohlen, die letzten beiden Ziffern in der Patch-Version 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. Diese Methode gibt eine Liste von MediationConfiguration-Objekten zurück, 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.
@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. Das Google Mobile Ads SDK fragt gleichzeitig Signale von allen Adaptern ab, die an Geboten teilnehmen. Bitte verhalte dich respektvoll und beschränke Anrufe in dieser Zeit auf den UI-Thread. Alle rechenintensiven Aufgaben, die Ihr Adapter oder Ihr SDK zum Erfassen von Signalen ausführen muss, sollten in der Methode initialize() ausgeführt und im Cache gespeichert werden.
Sobald Sie Ihre Signale haben, rufen Sie den onSuccess()-Callback mit Ihren codierten Signalen auf.
Hier ein Implementierungsbeispiel:
@Override
public void collectSignals(RtbSignalData rtbSignalData,
SignalCallbacks signalCallbacks) {
String signals = YourSdk.getSignals();
signalCallbacks.onSuccess(signals);
}
Wenn Ihr Adapter keine Signale erfasst, 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 zurückgibt, ruft das Google Mobile Ads SDK 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 der Anzeige benötigt.
Welche Methode genau aufgerufen wird, 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 von Ihrem Adapter unterstützt werden.
Die Methode „load“ wird im UI-Thread für dieselbe Adapterinstanz aufgerufen, über die 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 das Google Mobile Ads SDK benachrichtigt wird, wenn das Laden erfolgreich ist oder fehlschlägt.
Sobald das SDK die Anzeige geladen hat, rufen Sie mediationAdLoadCallback.onSuccess() auf. Wenn das Laden von Anzeigen fehlschlägt, rufen Sie mediationAdLoadCallback.onFailure() mit einem String auf, der den aufgetretenen Fehler beschreibt.
Für die mediationAdLoadCallback.onSuccess()-Methode muss ein Objekt übergeben werden, 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 die Methode getWatermark(), um einen Base64-codierten String zurückzugeben, der ein PNG-Bild darstellt. Dieses Bild sollte in einem transparenten Overlay in 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, mit denen Publisher die Quelle der angezeigten Anzeigen ermitteln können.
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 zu präsentieren. 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 finden Sie ein Beispiel für die Implementierung von loadBannerAd(). Die Implementierung Ihres Adapters sieht anders aus, 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.
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 Anzeigendarstellung weiterleiten
Der Adapter ist letztendlich dafür verantwortlich, das Google Mobile Ads SDK über alle Ereignisse im Präsentationslebenszyklus zu informieren, damit diese an den Publisher weitergeleitet werden können. Der Publisher erwartet diese Rückrufe zu bestimmten Zeiten, unabhängig davon, welches Werbenetzwerk die Anzeige ausliefert. Daher ist es wichtig, dass so viele dieser Rückrufe wie möglich und zum richtigen Zeitpunkt aufgerufen werden, damit das Google Mobile Ads SDK sie an den Publisher weiterleiten kann.
Adapter sollten gegebenenfalls die folgenden Ereignisse aufrufen:
| Für alle Formate | |
|---|---|
| Methode | Wann anrufen? |
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()
|
Der Nutzer hat die App aufgrund der Anzeige verlassen. |
| 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 bis zum Ende angesehen. |
Der Adapter erhält ein MediationAdLoadCallback<MediationAdT, MediationAdCallbackT>-Objekt zurück, wenn er mediationAdLoadCallback.onSuccess() aufruft. Adapter müssen dieses Objekt beibehalten und damit Präsentationsereignisse aufrufen, die in Ihrer Anzeige auftreten.
Die meisten dieser Ereignisse werden in der Regel durch das SDK Ihres Werbenetzwerks ausgelöst. Die Aufgabe des Adapters besteht lediglich darin, die Callbacks aus dem SDK Ihres Werbenetzwerks dem Google Mobile Ads SDK zuzuordnen.
Im folgenden Beispiel sehen Sie, wie Sie Callbacks vom Anzeigenlistener Ihres SDK 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 bei nativen Anzeigen
Das Google Mobile Ads SDK erfasst eine Impression für eine native Anzeige, wenn 1 Pixel der Anzeige sichtbar ist. Wenn für Ihr Werbenetzwerk-SDK bestimmte Assets erforderlich sind, um eine gültige Impression zu rendern, kann Ihr Bieter 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 nativen Assets.
Anzeigenfehler anzeigen
Bei Vollbildformaten wie Interstitial-Anzeigen und Anzeigen mit Prämie müssen Sie im Load-Callback „success“ eine Implementierung von MediationInterstitialAd oder MediationRewardedAd bereitstellen, damit das Google Mobile Ads SDK Ihren Adapter auffordern kann, die Anzeige auszuliefern.
Das Google Mobile Ads SDK geht davon aus, dass eine Anzeige, die von einem Adapter geladen wurde, bereit ist, wenn der Publisher sie ausliefern möchte. Das bedeutet, dass jeder Aufruf einer Anzeige zu einer Impression führen sollte.
Es kann jedoch vorkommen, dass Sie keine Anzeige schalten 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 Präsentations-Callbacks auf die Erfassung von Impressionen für Vollbildanzeigenformate auswirken:
| Rückruf | Ergebnis |
|---|---|
| onAdOpened() | Impression recorded
|
| onAdFailedToShow() | Impression failure1
|
| Keine der oben genannten Optionen für mehrere Sekunden | Impression recorded
|
1 Bei fehlgeschlagenen Impressionen wird Ihrem Werbenetzwerk die Impression nicht in Rechnung gestellt. Sie wirkt sich jedoch auf die Anpassung der Abrechnungsereignisrate aus. Weitere Informationen zu Signalen in der Gebotsanfrage
Das folgende Beispiel zeigt einen Lade-/Anzeigezyklus, 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, ...);
}
}