Eventi personalizzati di annunci nativi

Prerequisiti

Completa la configurazione degli eventi personalizzati.

Richiedere un annuncio nativo

Quando l'elemento pubblicitario dell'evento personalizzato viene raggiunto nella catena di mediazione a cascata, il metodo loadNativeAd() viene chiamato in base al nome della classe che hai fornito la creazione di un nuovo dell'evento. In questo caso, questo metodo è in SampleCustomEvent, che quindi chiama il metodo loadNativeAd() in SampleNativeCustomEventLoader.

Per richiedere un annuncio nativo, crea o modifica una classe che espanda Adapter a implementare loadNativeAd(). Se esiste già una classe che estende Adapter, implementare loadNativeAd() lì. Inoltre, crea una nuova classe da implementare UnifiedNativeAdMapper.

Nel nostro esempio di evento personalizzato, SampleCustomEvent estende la classe Adapter e poi delega a 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 è responsabile delle seguenti attività:

• Caricamento dell'annuncio nativo.

• Implementazione della classe UnifiedNativeAdMapper.

• Ricezione e generazione di report sui callback di eventi relativi all'annuncio all'SDK Google Mobile Ads.

Il parametro facoltativo definito nell'interfaccia utente di Ad Manager è incluse nella configurazione dell'annuncio. È possibile accedere al parametro tramite adConfiguration.getServerParameters().getString(MediationConfiguration.CUSTOM_EVENT_SERVER_PARAMETER_FIELD). In genere, questo parametro è un identificatore di unità pubblicitaria che un SDK della rete pubblicitaria richiede quando si crea un'istanza di un oggetto annuncio.

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

A seconda che l'annuncio sia stato recuperato correttamente o che abbia riscontrato un errore, chiamerebbe onSuccess() o onFailure(). onSuccess() viene chiamato passando un'istanza della classe che implementa MediationNativeAd.

In genere, questi metodi sono implementati all'interno dei callback SDK di terze parti implementato dall'adattatore. Per questo esempio, l'SDK di esempio ha un SampleAdListener con callback pertinenti:

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

Mappare gli annunci nativi

Ogni SDK ha i propri formati univoci per gli annunci nativi. Uno dei risultati potrebbe essere restituito che contengono un "titolo" campo, ad esempio, mentre un altro potrebbe "headline". Inoltre, i metodi utilizzati per tenere traccia delle impressioni i clic possono variare da un SDK all'altro.

UnifiedNativeAdMapper è responsabile della riconciliazione di queste differenze e adattando l'oggetto annuncio nativo di un SDK mediato in modo che corrisponda all'interfaccia prevista l'SDK Google Mobile Ads. Gli eventi personalizzati devono estendere questa classe per creare i propri mappatori specifici per l'SDK con mediazione. Ecco un esempio di mappatore di annunci il nostro progetto di evento personalizzato di esempio:

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

Ora diamo uno sguardo più da vicino al codice del costruttore.

Contenere un riferimento all'oggetto dell'annuncio nativo mediato

Il costruttore accetta il parametro SampleNativeAd, la classe dell'annuncio nativo utilizzata dall'SDK Sample per i suoi annunci nativi. Il mappatore ha bisogno di un riferimento annuncio mediato in modo che possa trasmettere eventi di clic e impressioni. SampleNativeAd è come variabile locale.

Impostare le proprietà degli asset mappati

Il costruttore utilizza l'oggetto SampleNativeAd per completare gli asset nel UnifiedNativeAdMapper.

Questo snippet ottiene i dati sui prezzi dell'annuncio con mediazione e li utilizza per impostare il prezzo:

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

In questo esempio, l'annuncio con mediazione memorizza il prezzo come double, mentre Ad Manager utilizza un String per lo stesso asset. La Mapper è responsabile della gestione di questi tipi di conversioni.

Asset immagine mappa

La mappatura degli asset immagine è più complessa della mappatura di tipi di dati come double o String. Le immagini possono essere scaricate automaticamente restituiti come valori URL. Anche le proporzioni pixel-dpi possono variare.

Per aiutarti a gestire questi dettagli, l'SDK Google Mobile Ads fornisce le NativeAd.Image corso. Più o meno nello stesso modo in cui devi creare una sottoclasse di UnifiedNativeAdMapper per mappare un annuncio nativo con mediazione, devi anche creare una sottoclasse NativeAd.Image durante la mappatura degli asset immagine.

Ecco un esempio per la classe SampleNativeMappedImage dell'evento personalizzato:

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 utilizza la classe dell'immagine mappata in questa riga per impostare asset immagine dell'icona di Mapper:

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

Aggiungi campi al pacchetto extra

Alcuni SDK mediati forniscono asset aggiuntivi oltre a quelli formato dell'annuncio nativo di Ad Manager. UnifiedNativeAdMapper include un metodo setExtras() utilizzato per trasferire questi asset publisher. SampleNativeAdMapper lo utilizza per l'SDK di esempio "grado di meraviglia" asset:

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

I publisher possono recuperare i dati utilizzando la classe NativeAd getExtras() .

Scegli Tu!

Il tuo evento personalizzato deve fornire un'icona Scegli Tu! utilizzando: Metodo setAdChoicesContent() su UnifiedNativeAdMapper. Ecco uno snippet di SampleNativeAdMapper che mostra come fornire l'icona Scegli Tu!:

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

Eventi di impressioni e clic

Sia l'SDK Google Mobile Ads sia l'SDK con mediazione devono sapere quando si verifica un'impressione o un clic, ma solo un SDK deve monitorare questi eventi. Là sono due approcci diversi che gli eventi personalizzati possono utilizzare, a seconda che l'evento l'SDK con mediazione supporta il monitoraggio delle impressioni e dei clic autonomamente.

Monitora clic e impressioni con l'SDK Google Mobile Ads

Se l'SDK con mediazione non esegue il proprio monitoraggio delle impressioni e dei clic, fornisce metodi per registrare clic e impressioni, l'SDK Google Mobile Ads può monitorare questi eventi e inviare una notifica all'adattatore. La Il corso UnifiedNativeAdMapper include due metodi: recordImpression() e handleClick() che è possibile implementare eventi personalizzati per richiamare il metodo corrispondente sulla Oggetto annuncio nativo:

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

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

Poiché SampleNativeAdMapper contiene un riferimento al codice nativo dell'SDK di esempio dell'oggetto annuncio, può chiamare il metodo appropriato sull'oggetto per segnalare un clic o un'impressione. Tieni presente che il metodo handleClick() richiede una parametro singolo: l'oggetto View corrispondente all'asset annuncio nativo che che hanno ricevuto il clic.

Monitora clic e impressioni con l'SDK con mediazione

Alcuni SDK mediati potrebbero preferire il monitoraggio dei clic e delle impressioni in autonomia. Nella in questo caso, devi sostituire il monitoraggio predefinito dei clic e delle impressioni eseguendo le due chiamate seguenti nel costruttore UnifiedNativeAdMapper:

setOverrideClickHandling(true);
setOverrideImpressionRecording(true);

Gli eventi personalizzati che sostituiscono il monitoraggio dei clic e delle impressioni sono obbligatori per Segnala gli eventi onAdClicked() e onAdImpression() a Google Mobile SDK Ads.

Per monitorare le impressioni e i clic, è probabile che l'SDK con mediazione abbia bisogno di accedere ai visualizzazioni per attivare il monitoraggio. L'evento personalizzato deve sostituire il valore trackViews() e usalo per trasmettere la visualizzazione dell'annuncio nativo all'annuncio SDK da monitorare. L'SDK di esempio del nostro progetto di esempio di evento personalizzato (da cui gli snippet di codice di questa guida sono stati utilizzati) non utilizza questo approccio; ma se come in questo caso, il codice dell'evento personalizzato sarebbe simile al seguente:

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

Se l'SDK con mediazione supporta il monitoraggio di singoli asset, può esaminare clickableAssetViews per vedere quali visualizzazioni devono essere rese cliccabili. Questa mappa è specificato da un nome asset in NativeAdAssetNames. UnifiedNativeAdMapper offre un metodo untrackView() corrispondente che gli eventi personalizzati possono sostituire rilasciare eventuali riferimenti alla visualizzazione e annullare l'associazione dell'annuncio all'annuncio nativo .

Inoltrare gli eventi di mediazione all'SDK Google Mobile Ads

Puoi trovare tutti i callback supportati dalla mediazione nel MediationNativeAdCallback documenti.

È importante che l'evento personalizzato inoltri il maggior numero di questi callback possibile, in modo che la tua app riceva questi eventi equivalenti dall'account Google l'SDK Mobile Ads. Ecco un esempio di utilizzo delle richiamate:

L'implementazione degli eventi personalizzati per gli annunci nativi è completata. L'esempio completo è disponibile su GitHub.