Entwicklung des Gebotsadapters

Dieser Leitfaden richtet sich an Werbenetzwerke, die einen Bidding-Adapter erstellen möchten. um an Echtzeitgeboten (Real-Time-Bidding, RTB) in der Google-Vermittlung teilnehmen zu können. Wenn Sie Sie sind Publisher, siehe Publisher-Vermittlung Anleitung.

Ein Gebotsadapter ist der clientseitige Teil der Integration. Der Adapter ermöglicht Ihrem Werbenetzwerk-SDK die Kommunikation mit dem Google Mobile Ads SDK, Anzeigen laden, die von der Gebotsfunktion ausgeliefert werden.

Damit Bidding richtig funktioniert, muss Ihr Adapter verschiedene Initialisierung, Signale sammeln, Anzeigen laden und Anzeigenlebenszyklus weiterleiten Ereignisse. In dieser Anleitung zeigen wir Ihnen, wie Ihr Adapter funktionieren sollte. die für diese Vorgänge implementiert wurden.

Hinweis :Für die Teilnahme an Bidding ist auch ein Bieter erforderlich, der auf OpenRTB-Anfragen Die Anweisungen zum Aufbau einer Gebotsfunktion finden Sie außerhalb des für den Anwendungsbereich dieses Leitfadens.

Workflow eines Bidding-Adapters

Initialisierung

Detaillierter Ablauf des gesamten Anfrage-Antwort-Rendering-Lebenszyklus eines Adapters:

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

• Schritte 4–7: Adapter initialisieren und Google Mobile Ads SDK zurückrufen sobald die Initialisierung abgeschlossen ist.

• Schritte 10–13: Erfassen Sie Signale von Ihrem Werbenetzwerk-SDK, die an Ihr für die Teilnahme an einer EZG-Anfrage zur Verfügung, und leiten sie an die Google Mobile-Website Ads SDK.

• Schritte 18 bis 21: Wenn Ihre Gebotsfunktion das erfolgreiche Gebot zurückgibt, laden Sie die Anzeige gemäß auf die Antwort der Gebotsfunktion. Nach dem Laden das Google Mobile Ads SDK benachrichtigen dass die Anzeige geladen wurde.

• Schritt 23 und höher: Google Mobile Ads bei der Auslieferung der Anzeige benachrichtigen SDK für Impressions- und Klickereignisse sowie andere Anzeigenereignisse, die auftreten während des Präsentationszyklus.

Hinweis: Das Google Mobile Ads SDK erfasst Impressionsereignisse separat. Es ist jedoch Außerdem ist es wichtig, dass Sie das Impressionsereignis Ihres Werbenetzwerks weiterleiten, auf Abweichungen prüfen.

Bidding Adapter implementieren

Um einen Gebotsadapter für das Google Mobile Ads SDK zu erstellen, müssen Sie Erweiterung der abstrakten Klasse RtbAdapter. Die folgenden Abschnitte jede abstrakte Methode in RtbAdapter erläutern.

getSDKVersionInfo()

Hier sollten Sie die Version Ihres SDKs zurückgeben. Diese Version wird an Ihr der OpenRTB-Anfrage gesendet wird.

Bei dieser Methode muss ein VersionInfo zurückgegeben werden. Das folgende Beispiel zeigt, wie können Sie die Stringversion Ihres SDKs in einen VersionInfo. konvertieren

@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 an Ihr der OpenRTB-Anfrage gesendet wird.

Das Open-Source- und versionierte Adapter verwenden Sie ein vierstelliges Adapterversionsschema, aber mit VersionInfo sind nur drei Ziffern. Um dieses Problem zu umgehen, empfiehlt es sich, die letzten beiden Ziffern in die Patch-Version, 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 im Adapter aufgerufen wird. Es ist nur einmal pro Sitzung aufgerufen. Bei dieser Methode wird eine Liste MediationConfiguration-Objekte, die die vollständige Liste der Placements in dieser App, die für Ihr Werbenetzwerk konfiguriert sind Sie können Schleifen über diese Liste, um die Anmeldedaten für jedes Placement zu parsen. und relevante Daten zur Initialisierung an dein SDK übergeben.

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

Hinweis: Die Methode initialize() wird für eine Wegwerfinstanz eines Adapters aufgerufen. Für diese Instanz werden keine anderen Methoden aufgerufen. Wenn Ihr Adapter den Status aufgrund dieser Methode speichern muss, sollte jeder 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 Ihrer RtbAdapter erstellt. erstellt und die Methode collectSignals() aufgerufen wird. Diese Instanz von RtbAdapter wird für die Dauer der Anzeigenanfrage, der Antwort und Rendering-Lebenszyklus für diese Anzeige. Die Methode collectSignals() aktiviert um Signale vom Gerät bereitzustellen, die dann in einem OpenRTB-Anfrage aus.

collectSignals() wird in einem Hintergrundthread aufgerufen. Das Google Mobile Ads SDK fordert gleichzeitig Signale von allen Adaptern an. die Teilnahme an Bidding. Seien Sie respektvoll und beschränken Sie Aufrufe an den UI-Thread. während dieser Zeit. Alle schweren Arbeiten, die Ihr Adapter oder SDK ausführen muss, um die Signale sollten in der Methode initialize() vorgenommen und im Cache gespeichert werden.

Sobald die Signale bereit sind, kannst du den onSuccess()-Callback mit deinem codierten Signalen.

Hier ist eine Beispielimplementierung:

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

Wenn der Adapter keine Signale erfasst, rufen Sie signalCallbacks.onFailure() auf. durch einen String, der den aufgetretenen Fehler erklärt.

Hinweis: Der Signalstring kann ein beliebiges Objekt und eine beliebige wie einfaches JSON-Format, Base64-codiert oder eine andere auswählen. Wir empfehlen die Verschlüsselung von Signalen, damit sie intransparent sind außerhalb Ihres Netzwerks.

Methoden zum Laden von Anzeigen implementieren

Zeitlimit: 10 Sekunden

Wenn Ihre Gebotsfunktion das erfolgreiche Gebot zurückgibt, wird das Google Mobile Ads SDK ruft Ihren Adapter auf, um die erfolgreiche Anzeige zu laden. Dabei werden Ihnen alle Daten übergeben, Der Bieter hat zurückgegeben, dass Ihr SDK diese Anzeige laden muss.

Die genaue Lademethode, die aufgerufen wird, hängt von der Anzeige ab Format dieser Anfrage:

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 Adapter, von dem Sie Signale bereitgestellt haben. Diese Methode bietet Ihnen Folgendes: Parameter:

• Eine MediationAdConfiguration mit den Parametern, die dein SDK benötigt Die Anzeige für das erfolgreiche Gebot laden, z. B. die Gebotsantwort und Anmeldedaten des Publishers in der AdMob-Benutzeroberfläche.

• Ein MediationAdLoadCallback-Objekt zur Benachrichtigung des Google Mobile Ads SDK wenn der Ladevorgang erfolgreich ist oder fehlschlägt.

Sobald Ihr SDK die Anzeige lädt, rufen Sie mediationAdLoadCallback.onSuccess() auf. Im Ereignis-Anzeigen laden schlägt fehl, rufen Sie mediationAdLoadCallback.onFailure() mit einer String zur Erläuterung des aufgetretenen Fehlers.

Für die Methode mediationAdLoadCallback.onSuccess() müssen Sie ein , das einer der „Ad“- vom Google Mobile-Tag Ads SDK. Auf diesen Oberflächen werden Sie aufgefordert, einige Informationen zur Anzeige anzugeben.

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

Bei Bannern werden Sie aufgefordert, die Banneransicht bereitzustellen. Für Interstitial- und Anzeigen mit Prämie werden Sie aufgefordert, eine show()-Methode zu implementieren, damit die Anzeige bei zu einem späteren Zeitpunkt erstellen. Als Best Practice empfehlen wir Ihnen, Ihren Kurs so einzurichten, Ist das Laden der Anzeige auch für die Implementierung dieser Anzeigenmethoden verantwortlich?

Im Folgenden sehen Sie eine Beispielimplementierung von loadBannerAd(). Wichtige Hinweise dass die Implementierung des Adapters anders aussieht, in ein anderes SDK integriert.

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

Lebenszyklusereignisse der Anzeigenpräsentation

Die letzte Aufgabe des Adapters besteht darin, das Google Mobile Ads SDK zu benachrichtigen. alle Lebenszyklus-Ereignisse einer Präsentation, damit sie an den Publisher. Der Publisher erwartet diese Callbacks zu bestimmten Zeiten, unabhängig davon, welches Werbenetzwerk die Anzeige schaltet, daher ist es wichtig, Callbacks wie möglich und zum richtigen Zeitpunkt aufgerufen werden, Über das Mobile Ads SDK können sie an den Publisher weitergeleitet werden.

Adapter sollten gegebenenfalls die folgenden Ereignisse aufrufen:

Allen Formaten gemeinsam
Methode	Zeitpunkt des Anrufs
reportAdClicked()	Die Anzeige wurde angeklickt.
reportAdImpression()	Die Anzeige hat eine Impression gerendert.
onAdOpened()	Die Anzeige präsentierte eine Vollbildansicht.
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-Rückrufe (Anzeigen mit Prämie und native Anzeigen)
onVideoStarted()	Das Video der Anzeige wurde gestartet.
onVideoCompleted()	Das Video der Anzeige ist abgeschlossen.

Der Adapter erhält eine MediationAdLoadCallback<MediationAdT, MediationAdCallbackT> zurück, nachdem mediationAdLoadCallback.onSuccess() aufgerufen wurde. Adapter sind wird erwartet, dass es dieses Objekt enthält und zum Aufrufen von Präsentationsereignissen verwendet. die in Ihrer Anzeige auftreten.

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

Das folgende Beispiel zeigt, wie Sie Rückrufe von Ihrem SDK-Anzeigen-Listener für das Google Mobile Ads SDK:

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 für native Anzeigen

Das Google Mobile Ads SDK erfasst eine Impression für eine native Anzeige, wenn 1 Pixel der sichtbar ist. Wenn für Ihr Werbenetzwerk-SDK bestimmte Assets erforderlich sind Damit eine gültige Impression gerendert wird, kann die Gebotsfunktion diese erforderlichen native Assets in die Gebotsantwort ein. Mit dem Google Mobile Ads SDK wird dann dass die erforderlichen nativen Assets zu sehen sind, bevor eine Impression erfasst wird.

Erforderliche Assets für native Anzeigen Dokumentation für Weitere Informationen dazu, wie Sie zusätzlich erforderliche Assets im Gebot angeben Antwort.

Wichtiger Hinweis: Alle Impressionen, die aufgrund der zusätzlichen die erforderlichen nativen Assets wirken sich auf das Verhältnis des abrechenbaren Ereignisses für diesen Publisher aus.

Anzeigenfehler anzeigen

Für Vollbildformate wie Interstitial-Anzeigen und Anzeigen mit Prämie laden Sie den Callback. Sie implementieren eine MediationInterstitialAd oder MediationRewardedAd damit das Google Mobile Ads SDK den Adapter anfordern kann, die Anzeige auszuliefern.

Das Google Mobile Ads SDK erwartet, dass, wenn eine Anzeige über einen Adapter geladen wurde, kann die Anzeige geschaltet werden, wenn der Publisher darum bittet. Das bedeutet, dass sollte jeder Aufruf einer Sendung zu einer Impression führen.

In seltenen Fällen kann es jedoch vorkommen, dass eine Anzeige nicht geschaltet werden kann. Wenn Sie die Anzeige nicht schalten kann, rufen Sie die Funktion onAdFailedToShow() zum Abbrechen der Impression zurück.

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 failure^1
Nichts davon für mehrere Sekunden	Impression recorded

¹ für fehlgeschlagen wird die Impression Ihrem Werbenetzwerk nicht in Rechnung gestellt, wirkt sich auf die Anpassung der Rate für abrechenbare Ereignisse aus. Gebotsanfrage ansehen Signalen für weitere Informationen.

Das folgende Beispiel zeigt einen Lade-/Sende-Lebenszyklus, Show-Aufruf kann zu einem Fehler führen.

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