Benutzerdefinierte Ereignisse für native Anzeigen

Vorbereitung

Schließen Sie die Einrichtung benutzerdefinierter Ereignisse ab.

Native Anzeige anfordern

Wenn die Werbebuchung für das benutzerdefinierte Ereignis in der abfolgebasierten Vermittlungskette erreicht wird, wird die Methode loadNativeAd() mit dem Klassennamen aufgerufen, den Sie beim Erstellen des benutzerdefinierten Ereignisses angegeben haben. In diesem Fall befindet sich diese Methode in SampleCustomEvent, die dann die Methode loadNativeAd() in SampleNativeCustomEventLoader aufruft.

Wenn Sie eine native Anzeige anfordern möchten, erstellen oder ändern Sie eine Klasse, die Adapter erweitert, um loadNativeAd() zu implementieren. Wenn bereits eine Klasse vorhanden ist, die Adapter erweitert, implementieren Sie loadNativeAd() dort. Erstellen Sie außerdem eine neue Klasse, um UnifiedNativeAdMapper zu implementieren.

In unserem Beispiel für ein benutzerdefiniertes Ereignis erweitert SampleCustomEvent die Klasse Adapter und delegiert dann an SampleNativeCustomEventLoader.

package com.google.ads.mediation.sample.customevent;

import com.google.android.gms.ads.mediation.Adapter;
import com.google.android.gms.ads.mediation.MediationAdConfiguration;
import com.google.android.gms.ads.mediation.MediationAdLoadCallback;

import com.google.android.gms.ads.mediation.MediationNativeAdCallback;
...
public class SampleCustomEvent extends Adapter {
  private SampleNativeCustomEventLoader nativeLoader;

  @Override
  public void loadNativeAd(
      @NonNull MediationNativeAdConfiguration adConfiguration,
      @NonNull MediationAdLoadCallback<UnifiedNativeAdMapper, MediationNativeAdCallback> callback) {
    nativeLoader = new SampleNativeCustomEventLoader(adConfiguration, callback);
    nativeLoader.loadAd();
  }
}

SampleNativeCustomEventLoader ist für die folgenden Aufgaben verantwortlich:

• Native Anzeige wird geladen.

• Implementierung der UnifiedNativeAdMapper-Klasse

• Callbacks für Anzeigenereignisse an das Google Mobile Ads SDK empfangen und melden

Der in der AdMob-Benutzeroberfläche definierte optionale Parameter ist in der Anzeigenkonfiguration enthalten. Der Parameter kann über adConfiguration.getServerParameters().getString(MediationConfiguration.CUSTOM_EVENT_SERVER_PARAMETER_FIELD) aufgerufen werden. Dieser Parameter ist in der Regel eine Anzeigenblock-ID, die von einem Werbenetzwerk-SDK beim Instanziieren eines Anzeigenobjekts benötigt wird.

package com.google.ads.mediation.sample.customevent;

import com.google.android.gms.ads.mediation.Adapter;
import com.google.android.gms.ads.mediation.MediationNativeAdConfiguration;
import com.google.android.gms.ads.mediation.MediationAdLoadCallback;
import com.google.android.gms.ads.mediation.MediationNativeAdCallback;
...

public class SampleNativeCustomEventLoader extends SampleNativeAdListener {
  /** Configuration for requesting the native ad from the third-party network. */
  private final MediationNativeAdConfiguration mediationNativeAdConfiguration;

  /** Callback that fires on loading success or failure. */
  private final MediationAdLoadCallback<UnifiedNativeAdMapper, MediationNativeAdCallback>
      mediationAdLoadCallback;

  /** Callback for native ad events. */
  private MediationNativeAdCallback nativeAdCallback;

  /** Constructor */
  public SampleNativeCustomEventLoader(
      @NonNull MediationNativeAdConfiguration mediationNativeAdConfiguration,
      @NonNull MediationAdLoadCallback<MediationNativeAd, MediationNativeAdCallback>
              mediationAdLoadCallback) {
    this.mediationNativeAdConfiguration = mediationNativeAdConfiguration;
    this.mediationAdLoadCallback = mediationAdLoadCallback;
  }

  /** Loads the native ad from the third-party ad network. */
  public void loadAd() {
    // Create one of the Sample SDK's ad loaders to request ads.
    Log.i("NativeCustomEvent", "Begin loading native ad.");
    SampleNativeAdLoader loader =
        new SampleNativeAdLoader(mediationNativeAdConfiguration.getContext());

    // All custom events have a server parameter named "parameter" that returns
    // back the parameter entered into the UI when defining the custom event.
    String serverParameter = mediationNativeAdConfiguration
        .getServerParameters()
        .getString(MediationConfiguration
        .CUSTOM_EVENT_SERVER_PARAMETER_FIELD);
    Log.d("NativeCustomEvent", "Received server parameter.");

    loader.setAdUnit(serverParameter);

    // Create a native request to give to the SampleNativeAdLoader.
    SampleNativeAdRequest request = new SampleNativeAdRequest();
    NativeAdOptions options = mediationNativeAdConfiguration.getNativeAdOptions();
    if (options != null) {
      // If the NativeAdOptions' shouldReturnUrlsForImageAssets is true, the adapter should
      // send just the URLs for the images.
      request.setShouldDownloadImages(!options.shouldReturnUrlsForImageAssets());

      request.setShouldDownloadMultipleImages(options.shouldRequestMultipleImages());
      switch (options.getMediaAspectRatio()) {
        case NativeAdOptions.NATIVE_MEDIA_ASPECT_RATIO_LANDSCAPE:
          request.setPreferredImageOrientation(SampleNativeAdRequest.IMAGE_ORIENTATION_LANDSCAPE);
          break;
        case NativeAdOptions.NATIVE_MEDIA_ASPECT_RATIO_PORTRAIT:
          request.setPreferredImageOrientation(SampleNativeAdRequest.IMAGE_ORIENTATION_PORTRAIT);
          break;
        case NativeAdOptions.NATIVE_MEDIA_ASPECT_RATIO_SQUARE:
        case NativeAdOptions.NATIVE_MEDIA_ASPECT_RATIO_ANY:
        case NativeAdOptions.NATIVE_MEDIA_ASPECT_RATIO_UNKNOWN:
        default:
          request.setPreferredImageOrientation(SampleNativeAdRequest.IMAGE_ORIENTATION_ANY);
      }
    }

    loader.setNativeAdListener(this);

    // Begin a request.
    Log.i("NativeCustomEvent", "Start fetching native ad.");
    loader.fetchAd(request);
  }
}

Je nachdem, ob die Anzeige erfolgreich abgerufen wurde oder ein Fehler aufgetreten ist, rufen Sie entweder onSuccess() oder onFailure() auf. onSuccess() wird aufgerufen, indem eine Instanz der Klasse übergeben wird, die MediationNativeAd implementiert.

Normalerweise werden diese Methoden in Callbacks aus dem SDK des Drittanbieters implementiert, das Sie in Ihrem Adapter verwenden. In diesem Beispiel hat das Beispiel-SDK eine SampleAdListener mit relevanten Callbacks:

@Override
public void onNativeAdFetched(SampleNativeAd ad) {
  SampleUnifiedNativeAdMapper mapper = new SampleUnifiedNativeAdMapper(ad);
  mediationNativeAdCallback = mediationAdLoadCallback.onSuccess(mapper);
}

@Override
public void onAdFetchFailed(SampleErrorCode errorCode) {
  mediationAdLoadCallback.onFailure(SampleCustomEventError.createSampleSdkError(errorCode));
}

Native Anzeigen auf Google Maps platzieren

Verschiedene SDKs haben unterschiedliche Formate für native Anzeigen. Eine Funktion kann beispielsweise Objekte zurückgeben, die ein Feld „Titel“ enthalten, während eine andere Funktion „Überschrift“ hat. Außerdem können die Methoden zum Erfassen von Impressionen und zum Verarbeiten von Klicks je nach SDK variieren.

Der UnifiedNativeAdMapper ist dafür verantwortlich, diese Unterschiede auszugleichen und das native Anzeigenobjekt eines vermittelten SDKs an die vom Google Mobile Ads SDK erwartete Benutzeroberfläche anzupassen. Für benutzerdefinierte Ereignisse sollte diese Klasse erweitert werden, um eigene Mapper für das vermittelte SDK zu erstellen. Hier ist ein Beispiel für einen Anzeigen-Mapper aus unserem Beispielprojekt für benutzerdefinierte Ereignisse:

package com.google.ads.mediation.sample.customevent;

import com.google.android.gms.ads.mediation.UnifiedNativeAdMapper;
import com.google.android.gms.ads.nativead.NativeAd;
...

public class SampleUnifiedNativeAdMapper extends UnifiedNativeAdMapper {

  private final SampleNativeAd sampleAd;

  public SampleUnifiedNativeAdMapper(SampleNativeAd ad) {
    sampleAd = ad;
    setHeadline(sampleAd.getHeadline());
    setBody(sampleAd.getBody());
    setCallToAction(sampleAd.getCallToAction());
    setStarRating(sampleAd.getStarRating());
    setStore(sampleAd.getStoreName());
    setIcon(
        new SampleNativeMappedImage(
            ad.getIcon(), ad.getIconUri(), SampleCustomEvent.SAMPLE_SDK_IMAGE_SCALE));
    setAdvertiser(ad.getAdvertiser());

    List<NativeAd.Image> imagesList = new ArrayList<NativeAd.Image>();
    imagesList.add(new SampleNativeMappedImage(ad.getImage(), ad.getImageUri(),
        SampleCustomEvent.SAMPLE_SDK_IMAGE_SCALE));
    setImages(imagesList);

    if (sampleAd.getPrice() != null) {
      NumberFormat formatter = NumberFormat.getCurrencyInstance();
      String priceString = formatter.format(sampleAd.getPrice());
      setPrice(priceString);
    }

    Bundle extras = new Bundle();
    extras.putString(SampleCustomEvent.DEGREE_OF_AWESOMENESS, ad.getDegreeOfAwesomeness());
    this.setExtras(extras);

    setOverrideClickHandling(false);
    setOverrideImpressionRecording(false);

    setAdChoicesContent(sampleAd.getInformationIcon());
  }

  @Override
  public void recordImpression() {
    sampleAd.recordImpression();
  }

  @Override
  public void handleClick(View view) {
    sampleAd.handleClick(view);
  }

  // The Sample SDK doesn't do its own impression/click tracking, instead relies on its
  // publishers calling the recordImpression and handleClick methods on its native ad object. So
  // there's no need to pass a reference to the View being used to display the native ad. If
  // your mediated network does need a reference to the view, the following method can be used
  // to provide one.

  @Override
  public void trackViews(View containerView, Map<String, View> clickableAssetViews,
      Map<String, View> nonClickableAssetViews) {
    super.trackViews(containerView, clickableAssetViews, nonClickableAssetViews);
    // If your ad network SDK does its own impression tracking, here is where you can track the
    // top level native ad view and its individual asset views.
  }

  @Override
  public void untrackView(View view) {
    super.untrackView(view);
    // Here you would remove any trackers from the View added in trackView.
  }
}

Sehen wir uns nun den Code des Konstruktors genauer an.

Verweis auf das vermittelte native Anzeigenobjekt beibehalten

Der Konstruktor akzeptiert den Parameter SampleNativeAd, die native Anzeigenklasse, die vom Sample SDK für seine nativen Anzeigen verwendet wird. Der Mapper benötigt eine Referenz auf die vermittelte Anzeige, damit Klick- und Impressionsereignisse übergeben werden können. SampleNativeAd wird als lokale Variable gespeichert.

Zugewiesene Asset-Properties festlegen

Der Konstruktor verwendet das SampleNativeAd-Objekt, um Assets in der UnifiedNativeAdMapper zu füllen.

In diesem Snippet werden die Preisdaten der vermittelten Anzeige abgerufen und verwendet, um den Preis des Mappers festzulegen:

if (sampleAd.getPrice() != null) {
    NumberFormat formatter = NumberFormat.getCurrencyInstance();
    String priceString = formatter.format(sampleAd.getPrice());
    setPrice(priceString);
}

In diesem Beispiel wird der Preis in der vermittelten Anzeige als double gespeichert, während AdMob für dasselbe Asset eine String verwendet. Der Mapper ist für die Verarbeitung dieser Conversion-Typen verantwortlich.

Bild-Assets zuordnen

Die Zuordnung von Bild-Assets ist komplizierter als die von Datentypen wie double oder String. Bilder können automatisch heruntergeladen oder als URL-Werte zurückgegeben werden. Auch die Skalierung von Pixeln in dpi kann variieren.

Zur Verwaltung dieser Details bietet das Google Mobile Ads SDK die Klasse NativeAd.Image. Ähnlich wie Sie eine untergeordnete Klasse von UnifiedNativeAdMapper erstellen müssen, um eine vermittelte native Anzeige abzubilden, sollten Sie auch eine untergeordnete Klasse von NativeAd.Image erstellen, wenn Sie Bild-Assets zuordnen.

Hier ist ein Beispiel für die SampleNativeMappedImage-Klasse des benutzerdefinierten Ereignisses:

public class SampleNativeMappedImage extends NativeAd.Image {

  private Drawable drawable;
  private Uri imageUri;
  private double scale;

  public SampleNativeMappedImage(Drawable drawable, Uri imageUri, double scale) {
    this.drawable = drawable;
    this.imageUri = imageUri;
    this.scale = scale;
  }

  @Override
  public Drawable getDrawable() {
    return drawable;
  }

  @Override
  public Uri getUri() {
    return imageUri;
  }

  @Override
  public double getScale() {
    return scale;
  }
}

In dieser Zeile verwendet SampleNativeAdMapper seine zugeordnete Bildklasse, um das Symbolbild-Asset des Mappers festzulegen:

setIcon(new SampleNativeMappedImage(ad.getAppIcon(), ad.getAppIconUri(),
    SampleCustomEvent.SAMPLE_SDK_IMAGE_SCALE));

Dem Extras-Bundle Felder hinzufügen

Einige vermittelte SDKs bieten zusätzliche Assets, die über die im nativen Anzeigenformat von AdMob verfügbaren hinausgehen. Die Klasse UnifiedNativeAdMapper enthält eine setExtras()-Methode, mit der diese Assets an Publisher übergeben werden. Im SampleNativeAdMapper wird dies für das Asset „degree of awesomeness“ (Grad der Coolness) des Beispiel-SDKs verwendet:

Bundle extras = new Bundle();
extras.putString(SampleCustomEvent.DEGREE_OF_AWESOMENESS, ad.getDegreeOfAwesomeness());
this.setExtras(extras);

Publisher können die Daten mit der Methode getExtras() der Klasse NativeAd abrufen.

Datenschutzinfo

Ihr benutzerdefiniertes Ereignis ist dafür verantwortlich, ein Datenschutzinfo-Symbol mit der Methode setAdChoicesContent() auf UnifiedNativeAdMapper bereitzustellen. Hier ist ein Snippet aus SampleNativeAdMapper, das zeigt, wie das AdChoices-Symbol bereitgestellt wird:

public SampleNativeAdMapper(SampleNativeAd ad) {
    ...
    setAdChoicesContent(sampleAd.getInformationIcon());
}

Impressions- und Klickereignisse

Sowohl das Google Mobile Ads SDK als auch das vermittelte SDK müssen wissen, wann eine Impression oder ein Klick erfolgt. Diese Ereignisse müssen jedoch nur von einem SDK erfasst werden. Es gibt zwei verschiedene Ansätze für benutzerdefinierte Ereignisse, je nachdem, ob das vermittelte SDK das Tracking von Impressionen und Klicks unterstützt.

Klicks und Impressionen mit dem Google Mobile Ads SDK erfassen

Wenn das vermittelte SDK kein eigenes Impressions- und Klick-Tracking durchführt, aber Methoden zum Erfassen von Klicks und Impressionen bietet, kann das Google Mobile Ads SDK diese Ereignisse erfassen und den Adapter benachrichtigen. Die Klasse UnifiedNativeAdMapper enthält zwei Methoden: recordImpression() und handleClick(). Diese können in benutzerdefinierten Ereignissen implementiert werden, um die entsprechende Methode auf dem vermittelten nativen Anzeigenobjekt aufzurufen:

@Override
public void recordImpression() {
  sampleAd.recordImpression();
}

@Override
public void handleClick(View view) {
  sampleAd.handleClick(view);
}

Da SampleNativeAdMapper einen Verweis auf das native Anzeigenobjekt des Sample SDK enthält, kann die entsprechende Methode für dieses Objekt aufgerufen werden, um einen Klick oder eine Impression zu erfassen. Die Methode handleClick() nimmt einen einzelnen Parameter an: das View-Objekt, das dem nativen Anzeigen-Asset entspricht, auf das der Klick erfolgte.

Klicks und Impressionen mit dem vermittelten SDK erfassen

Bei einigen vermittelten SDKs werden Klicks und Impressionen möglicherweise lieber selbst erfasst. In diesem Fall sollten Sie das standardmäßige Klick- und Impressions-Tracking überschreiben. Führen Sie dazu die folgenden beiden Aufrufe im Konstruktor Ihrer UnifiedNativeAdMapper aus:

setOverrideClickHandling(true);
setOverrideImpressionRecording(true);

Benutzerdefinierte Ereignisse, die das Klick- und Impressions-Tracking überschreiben, sind erforderlich, um die Ereignisse onAdClicked() und onAdImpression() an das Google Mobile Ads SDK zu senden.

Um Impressionen und Klicks zu erfassen, benötigt das vermittelte SDK wahrscheinlich Zugriff auf die Aufrufe, um das Tracking zu ermöglichen. Das benutzerdefinierte Ereignis sollte die Methode trackViews() überschreiben und die Ansicht der nativen Anzeige an das vermittelte SDK zum Tracking weitergeben. Im Beispiel-SDK aus unserem Beispielprojekt für benutzerdefinierte Ereignisse (aus dem die Code-Snippets in diesem Leitfaden stammen) wird dieser Ansatz nicht verwendet. Andernfalls würde der Code für benutzerdefinierte Ereignisse in etwa so aussehen:

@Override
public void trackViews(View containerView,
    Map<String, View> clickableAssetViews,
    Map<String, View> nonClickableAssetViews) {
  sampleAd.setNativeAdViewForTracking(containerView);
}

Wenn das vermittelte SDK das Tracking einzelner Assets unterstützt, kann es in clickableAssetViews nachsehen, welche Ansichten anklickbar gemacht werden sollen. Diese Zuordnung ist in NativeAdAssetNames anhand eines Asset-Namens geordnet. UnifiedNativeAdMapper bietet eine entsprechende untrackView()-Methode, die von benutzerdefinierten Ereignissen überschrieben werden kann, um alle Verweise auf die Ansicht freizugeben und die Verknüpfung mit dem nativen Anzeigenobjekt aufzuheben.

Vermittlungsereignisse an das Google Mobile Ads SDK weiterleiten

Eine Liste aller von der Vermittlung unterstützten Rückrufe findest du in der MediationNativeAdCallback-Dokumentation.

Es ist wichtig, dass Ihr benutzerdefiniertes Ereignis so viele dieser Rückrufe wie möglich weiterleitet, damit Ihre App diese entsprechenden Ereignisse vom Google Mobile Ads SDK empfängt. Hier ein Beispiel für die Verwendung von Callbacks:

Damit ist die Implementierung benutzerdefinierter Ereignisse für native Anzeigen abgeschlossen. Das vollständige Beispiel finden Sie auf GitHub.