Benutzerdefinierte Ereignisse für native Anzeigen

Plattform auswählen: Android (Beta) Neu Android iOS

Vorbereitung

Schließen Sie die Einrichtung benutzerdefinierter Ereignisse ab.

Native Anzeige anfordern

Wenn die Werbebuchung für das benutzerdefinierte Ereignis in der Wasserfall-Mediationskette erreicht wird, wird die Methode loadNativeAd() für den Klassennamen aufgerufen, den Sie beim Erstellen des benutzerdefinierten Ereignisses angegeben haben. In diesem Fall befindet sich die 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, SampleCustomEvent erweitert die Klasse Adapter und delegiert dann an SampleNativeCustomEventLoader.

Java

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 laden

  • Klasse UnifiedNativeAdMapper implementieren

  • Anzeigenereignis-Callbacks empfangen und an Google Mobile Ads SDK melden

Der optionale Parameter, der in der AdMob-UI definiert ist, ist in der Anzeigenkonfiguration enthalten. Auf den Parameter kann über adConfiguration.getServerParameters().getString(MediationConfiguration.CUSTOM_EVENT_SERVER_PARAMETER_FIELD) zugegriffen werden. Dieser Parameter ist in der Regel eine Anzeigenblock-ID, die ein Werbenetzwerk-SDK benötigt, wenn ein Anzeigenobjekt instanziiert wird.

Java

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.

In der Regel werden diese Methoden in Callbacks aus dem Drittanbieter-SDK implementiert, das Ihr Adapter implementiert. In diesem Beispiel hat das Beispiel-SDK einen SampleAdListener mit relevanten Callbacks:

Java

@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 zuordnen

Verschiedene SDKs haben eigene Formate für native Anzeigen. Ein SDK gibt beispielsweise Objekte mit einem Feld „title“ zurück, während ein anderes „headline“ verwendet. Außerdem können sich die Methoden zum Erfassen von Impressionen und zum Verarbeiten von Klicks von SDK zu SDK unterscheiden.

Der UnifiedNativeAdMapper ist dafür verantwortlich, diese Unterschiede auszugleichen und das native Anzeigenobjekt eines Mediations-SDK so anzupassen, dass es der Schnittstelle entspricht, die von Google Mobile Ads SDK erwartet wird. Benutzerdefinierte Ereignisse sollten diese Klasse erweitern, um eigene Mapper zu erstellen, die speziell auf das Mediations-SDK zugeschnitten sind. Hier ist ein Beispiel für einen Anzeigen-Mapper aus unserem Beispielprojekt für benutzerdefinierte Ereignisse:

Java

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

Wir sehen uns jetzt den Konstruktorcode genauer an.

Verweis auf das native Mediations-Anzeigenobjekt beibehalten

Der Konstruktor akzeptiert den Parameter SampleNativeAd, die native Anzeigenklasse, die vom Beispiel-SDK für seine nativen Anzeigen verwendet wird. Der Mapper benötigt einen Verweis auf die Mediationsanzeige, damit er Klick- und Impressionsereignisse weitergeben kann. SampleNativeAd wird als lokale Variable gespeichert.

Zugeordnete Asset-Eigenschaften festlegen

Der Konstruktor verwendet das Objekt SampleNativeAd, um Assets in UnifiedNativeAdMapper einzufügen.

Dieses Snippet ruft die Preisdaten der Mediationsanzeige ab und verwendet sie, um den Preis des Mappers festzulegen:

Java

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

In diesem Beispiel speichert die Mediationsanzeige den Preis als double, während AdMob für dasselbe Asset String verwendet. Der Mapper ist für die Verarbeitung dieser Arten von Conversions verantwortlich.

Bild-Assets zuordnen

Das Zuordnen von Bild-Assets ist komplizierter als das Zuordnen von Datentypen wie double oder String. Bilder werden möglicherweise automatisch heruntergeladen oder als URL-Werte zurückgegeben. Auch die Pixel-zu-dpi-Skalierungen können variieren.

Um Ihnen die Verwaltung dieser Details zu erleichtern, bietet Google Mobile Ads SDK die NativeAd.Image Klasse. So wie Sie eine Unterklasse von UnifiedNativeAdMapper erstellen müssen, um eine native Mediationsanzeige zuzuordnen, sollten Sie auch eine Unterklasse von NativeAd.Image erstellen, wenn Sie Bild-Assets zuordnen.

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

Java

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 die zugeordnete Bildklasse, um das Symbol-Asset des Mappers festzulegen:

Java

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

Felder zum Extras-Bundle hinzufügen

Einige Mediations-SDKs bieten zusätzliche Assets, die über die im nativen Anzeigenformat von AdMob enthaltenen Assets hinausgehen. Die Klasse UnifiedNativeAdMapper enthält eine Methode setExtras(), mit der diese Assets an Publisher weitergegeben werden. SampleNativeAdMapper verwendet diese Methode für das Asset „degree of awesomeness“ des Beispiel-SDK:

Java

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.

AdChoices

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

Java

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

Impressionen und Klicks

Sowohl Google Mobile Ads SDK als auch das Mediations-SDK müssen wissen, wann eine Impression oder ein Klick erfolgt. Nur eines der beiden SDKs muss diese Ereignisse erfassen. Es gibt zwei verschiedene Ansätze, die für benutzerdefinierte Ereignisse verwendet werden können. Sie hängen davon ab, ob das Mediations-SDK Impressionen und Klicks selbst erfassen kann.

Klicks und Impressionen mit Google Mobile Ads SDK erfassen

Wenn das Mediations-SDK keine eigene Erfassung von Impressionen und Klicks durchführt, aber Methoden zum Aufzeichnen von Klicks und Impressionen bietet, kannGoogle Mobile Ads SDKdiese Ereignisse erfassen und den Adapter benachrichtigen. Die Klasse UnifiedNativeAdMapper enthält zwei Methoden: recordImpression() und handleClick(), die für benutzerdefinierte Ereignisse implementiert werden können, um die entsprechende Methode für das native Mediations-Anzeigenobjekt aufzurufen:

Java

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

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

Da SampleNativeAdMapper einen Verweis auf das native Anzeigenobjekt des Beispiel-SDK enthält, kann es die entsprechende Methode für dieses Objekt aufrufen, um einen Klick oder eine Impression zu melden. Die Methode handleClick() hat einen einzelnen Parameter: das Objekt View, das dem nativen Anzeigen-Asset entspricht, für das der Klick erfasst wurde.

Klicks und Impressionen mit dem Mediations-SDK erfassen

Einige Mediations-SDKs erfassen Klicks und Impressionen möglicherweise selbst. In diesem Fall sollten Sie die Standarderfassung von Klicks und Impressionen überschreiben, indem Sie die folgenden beiden Aufrufe im Konstruktor von UnifiedNativeAdMapper ausführen:

Java

setOverrideClickHandling(true);
setOverrideImpressionRecording(true);

Benutzerdefinierte Ereignisse, die die Erfassung von Klicks und Impressionen überschreiben, müssen die Ereignisse onAdClicked() und onAdImpression() an das Google Mobile Ads SDK melden.

Um Impressionen und Klicks zu erfassen, benötigt das Mediations-SDK wahrscheinlich Zugriff auf die Ansichten, um die Erfassung zu aktivieren. Das benutzerdefinierte Ereignis sollte die Methode trackViews() überschreiben und verwenden, um die Ansicht der nativen Anzeige an das Mediations-SDK zu übergeben, damit sie erfasst werden kann. Das Beispiel-SDK aus unserem Beispielprojekt für benutzerdefinierte Ereignisse (aus dem die Code-Snippets in dieser Anleitung stammen) verwendet diesen Ansatz nicht. Wenn es ihn verwenden würde, sähe der Code für das benutzerdefinierte Ereignis so aus:

Java

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

Wenn das Mediations-SDK die Erfassung einzelner Assets unterstützt, kann es in clickableAssetViews nachsehen, welche Ansichten klickbar gemacht werden sollen. Dieser Zuordnungsschlüssel ist ein Asset-Name in NativeAdAssetNames. UnifiedNativeAdMapper bietet eine entsprechende Methode untrackView(), die für benutzerdefinierte Ereignisse überschrieben werden kann, um alle Verweise auf die Ansicht freizugeben und sie vom nativen Anzeigenobjekt zu trennen.

Mediationsereignisse an Google Mobile Ads SDK weiterleiten

Alle von der Mediation unterstützten Callbacks finden Sie in der MediationNativeAdCallback Dokumentation.

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

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