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, wodurch die Methode loadNativeAd() in SampleNativeCustomEventLoader.

Wenn Sie eine native Anzeige anfordern möchten, erstellen oder ändern Sie eine Klasse, die Adapter auf loadNativeAd() 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 benutzerdefinierte Ereignisse SampleCustomEvent erweitert die Klasse Adapter und delegiert dann 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:

  • Die native Anzeige wird geladen.

  • Klasse UnifiedNativeAdMapper implementieren

  • Empfangen und Melden von Callbacks für Anzeigenereignisse an das Google Mobile Ads SDK

Der optionale Parameter in der AdMob-Benutzeroberfläche ist die in der Anzeigenkonfiguration enthalten sind. Der Zugriff auf den Parameter ist über adConfiguration.getServerParameters().getString(MediationConfiguration.CUSTOM_EVENT_SERVER_PARAMETER_FIELD) Dieser Parameter ist in der Regel eine Anzeigenblock-ID, die vom SDK eines Werbenetzwerks beim Instanziieren eines Anzeigenobjekts erforderlich ist.

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 auftritt, rufen Sie entweder onSuccess() oder onFailure() onSuccess() wird aufgerufen, indem eine Instanz der Klasse übergeben wird, die MediationNativeAd implementiert.

Üblicherweise werden diese Methoden innerhalb von Callbacks vom Drittanbieter-SDK Ihres Adapters. In diesem Beispiel hat das Beispiel-SDK eine 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 auf Google Maps platzieren

Die verschiedenen SDKs haben eigene Formate für native Anzeigen. Jemand könnte zurückkehren Objekte, die einen „title“ enthalten während ein anderes Feld „headline“. Außerdem können die Methoden zum Erfassen von Impressionen und zum Verarbeiten von Klicks von SDK zu SDK variieren.

Der UnifiedNativeAdMapper ist für den Ausgleich dieser Unterschiede verantwortlich und das native Anzeigenobjekt eines vermittelten SDKs an die von das Google Mobile Ads SDK. Benutzerdefinierte Ereignisse sollten diese Klasse erweitern, um eigenen Kartografen, die für ihr vermitteltes SDK spezifisch 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.
  }
}

Sehen wir uns nun den Konstruktorcode genauer an.

Verweis auf das vermittelte native Anzeigenobjekt

Der Konstruktor akzeptiert den Parameter SampleNativeAd, die native Anzeigenklasse, die vom Sample SDK für seine nativen Anzeigen verwendet wird. Der Kartograf benötigt einen Verweis auf die vermittelte Anzeige, damit sie Klick- und Impressionsereignisse weitergeben kann. SampleNativeAd ist als lokale Variable gespeichert.

Zugewiesene Asset-Properties festlegen

Der Konstruktor verwendet das SampleNativeAd-Objekt, um Assets im UnifiedNativeAdMapper.

Dieses Snippet ruft die Preisdaten der vermittelten Anzeige ab und legt damit die Preis:

Java

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

Das Zuordnen von Bild-Assets ist komplizierter als das Zuordnen 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 bei der Erstellung einer Unterklasse von UnifiedNativeAdMapper, um eine vermittelte native Anzeige zuzuordnen, sollten Sie auch eine von NativeAd.Image beim Zuordnen von Bild-Assets verwendet wird.

Hier ist ein Beispiel für die SampleNativeMappedImage-Klasse 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;
  }
}

SampleNativeAdMapper verwendet die zugeordnete Bildklasse in dieser Zeile, um den Wert für Symbol-Bild-Asset des Kartografen:

Java

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

Felder zum Extras-Bundle hinzufügen

Einige vermittelte SDKs bieten zusätzliche Assets, die über die in der natives AdMob-Anzeigenformat. Das UnifiedNativeAdMapper enthält eine setExtras()-Methode, mit der diese Assets an Verlagen und Webpublishern. Der SampleNativeAdMapper nutzt diesen Wert für die „Grad an Tollität“ Asset:

Java

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

Verlage und Webpublisher können die Daten mithilfe der Klasse NativeAd abrufen. getExtras() .

Datenschutzinfo

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

Java

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 stehen für zwei verschiedene Ansätze für benutzerdefinierte Ereignisse, Vermitteltes SDK unterstützt das eigenständige Tracking von Impressionen und Klicks.

Klicks und Impressionen mit dem Google Mobile Ads SDK erfassen

Wenn das vermittelte SDK kein eigenes Impressions- und Klick-Tracking ausführt, Methoden zur Erfassung von Klicks und Impressionen zur Verfügung stellt, können Sie mit dem Google Mobile Ads SDK verfolgen Sie diese Ereignisse und benachrichtigen Sie den Adapter. 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:

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

Einige vermittelte SDKs möchten Klicks und Impressionen möglicherweise selbst erfassen. In in diesem Fall das standardmäßige Klick- und Impressions-Tracking überschreiben, die folgenden beiden Aufrufe im Konstruktor Ihres UnifiedNativeAdMapper:

Java

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.

Für das Tracking von Impressionen und Klicks benötigt das vermittelte SDK wahrscheinlich Zugriff auf den Ansichten, um das Tracking zu aktivieren. Das benutzerdefinierte Ereignis sollte die Methode trackViews() überschreiben und die Ansicht der nativen Anzeige an das vermittelte SDK zum Tracking weitergeben. Das Beispiel-SDK aus unserem Beispielprojekt für benutzerdefinierte Ereignisse (aus dem Code-Snippets dieses Leitfadens verwendet wurden, verwendet diesen Ansatz nicht. Wenn aber würde der benutzerdefinierte Ereigniscode ungefähr so aussehen:

Java

@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. Das UnifiedNativeAdMapper bietet eine entsprechende untrackView()-Methode, die von benutzerdefinierten Ereignissen überschrieben werden kann. um alle Verweise auf den Aufruf freizugeben und seine Verknüpfung mit der nativen Anzeige zu trennen. -Objekt enthält.

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. Vollständiges Beispiel ist verfügbar auf GitHub