Questa pagina è stata tradotta dall'API Cloud Translation.

Eventi personalizzati degli 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,the loadNativeAd() method viene chiamato in base al nome della classe che hai fornito durante la creazione di un evento personalizzato. In questo caso, il metodo è in SampleCustomEvent, che a sua volta chiama the loadNativeAd() method in SampleNativeCustomEventLoader.

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

Nel nostro esempio di evento personalizzato, SampleCustomEvent implementathe Adapter interface e poi delega aSampleNativeCustomEventLoader.

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 è responsabile delle seguenti attività:

Caricamento dell'annuncio nativo in corso...
Implementazione della UnifiedNativeAdMapper interface
Ricevere e generare report sui callback degli eventi annuncio nell'SDK Google Mobile Ads

Il parametro facoltativo definito nell' Ad Manager interfaccia utente è incluso nella configurazione dell'annuncio. È possibile accedere al parametro tramite adConfiguration.getServerParameters().getString(MediationConfiguration.CUSTOM_EVENT_SERVER_PARAMETER_FIELD). Questo parametro è in genere un identificatore di unità pubblicitaria richiesto dall'SDK di una rete pubblicitaria per creare l'istanza di un oggetto dell'annuncio.

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

A seconda che l'annuncio venga recuperato correttamente o che si verifichi un errore, puoi chiamare onSuccess() o onFailure(). onSuccess() viene chiamato passando un'istanza della classe che implementa MediationNativeAd.

In genere, questi metodi vengono implementati all'interno dei callback dell'SDK di terze parti implementato dal tuo adattatore. Per questo esempio, l'SDK Sample ha un valore SampleAdListener con callback pertinenti:

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

Mappare gli annunci nativi

SDK diversi hanno formati unici per gli annunci nativi. Uno potrebbe restituire oggetti che contengono un campo "titolo", ad esempio, mentre un altro potrebbe avere un "titolo". Inoltre, i metodi utilizzati per monitorare le impressioni e i clic di elaborazione possono variare da un SDK all'altro.

UnifiedNativeAdMapper è responsabile di riconciliare queste differenze e di adattare l'oggetto annuncio nativo di un SDK con mediazione in modo che corrisponda all'interfaccia prevista dall'SDK Google Mobile Ads. Gli eventi personalizzati dovrebbero estendere il corso per creare i loro mappatori specifici per l'SDK con mediazione. Ecco un esempio di mappatore di annunci tratto dal nostro progetto di evento personalizzato di esempio:

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

Ora diamo un'occhiata più da vicino al codice del costruttore.

Contiene un riferimento all'oggetto dell'annuncio nativo con mediazione

Il costruttore accetta il parametro SampleNativeAd, la classe di annunci nativi utilizzata dall'SDK di esempio per i suoi annunci nativi. Il mappatore ha bisogno di un riferimento all'annuncio con mediazione in modo da trasmettere eventi di clic e impressioni. SampleNativeAd viene archiviato come variabile locale.

Impostare le proprietà degli asset mappati

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

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

Java

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 String per lo stesso asset. Il mappatore è responsabile della gestione di questi tipi di conversioni.

Asset immagine mappa

La mappatura degli asset immagine è più complicata rispetto alla mappatura dei tipi di dati come double o String. Le immagini possono essere scaricate automaticamente o restituite come valori URL. Anche le scale da pixel a dpi possono variare.

Per aiutarti a gestire questi dettagli, l'SDK Google Mobile Ads fornisce la classe NativeAd.Image. Nello stesso modo in cui devi creare una sottoclasse UnifiedNativeAdMapper per mappare un annuncio nativo con mediazione, devi anche creare una sottoclasse NativeAd.Image quando esegui la mappatura degli asset immagine.

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

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 utilizza la propria classe dell'immagine mappata in questa riga per impostare l'asset immagine dell'icona del mappatore:

Java

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

Aggiungi campi al bundle extra

Alcuni SDK con mediazione forniscono asset aggiuntivi oltre a quelli nel Ad Manager formato dell'annuncio nativo. La classe UnifiedNativeAdMapper include un metodo setExtras() utilizzato per trasferire questi asset ai publisher. L'elemento SampleNativeAdMapper utilizza questo elemento per il "grado di qualità" dell'SDK di esempio:

Java

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

Gli editori possono recuperare i dati utilizzando il metodo getExtras() della classe NativeAd.

AdChoices

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

Java

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

Eventi di impressioni e clic

Sia l'SDK Google Mobile Ads che l'SDK con mediazione devono sapere quando si verifica un'impressione o un clic, ma è sufficiente un solo SDK per monitorare questi eventi. Esistono due diversi approcci che possono essere utilizzati per gli eventi personalizzati, a seconda che l'SDK con mediazione supporti il monitoraggio di impressioni e clic autonomamente.

Monitorare clic e impressioni con l'SDK Google Mobile Ads

Se l'SDK con mediazione non esegue il monitoraggio di impressioni e clic, ma fornisce metodi per registrare clic e impressioni, l'SDK Google Mobile Ads può monitorare questi eventi e inviare una notifica all'adattatore.UnifiedNativeAdMapper interface Include due metodi:recordImpression() e handleClick() gli eventi personalizzati possono implementare per chiamare il metodo corrispondente nell'oggetto annuncio nativo con mediazione:

Java

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

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

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

Monitorare clic e impressioni con l'SDK con mediazione

Alcuni SDK con mediazione potrebbero preferire monitorare in modo indipendente clic e impressioni. In questo caso, devi sostituire il monitoraggio predefinito dei clic e delle impressioni effettuando le due chiamate seguenti nel costruttore di UnifiedNativeAdMapper:

Java

setOverrideClickHandling(true);
setOverrideImpressionRecording(true);

Gli eventi personalizzati che sostituiscono il monitoraggio di clic e impressioni sono necessari per segnalare gli eventi onAdClicked() e onAdImpression() all'SDK Google Mobile Ads.

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

Java

@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ò guardare all'interno di clickableAssetViews per vedere quali viste rendere cliccabili. Questa mappa è associata al nome di un asset in NativeAdAssetNames. L'UnifiedNativeAdMapper offre un metodo untrackView() corrispondente che gli eventi personalizzati possono sostituire per rilasciare eventuali riferimenti alla visualizzazione e dissociarli dall'oggetto dell'annuncio nativo.

Inoltrare gli eventi di mediazione all'SDK Google Mobile Ads

Puoi trovare tutti i callback supportati dalla mediazione nella documentazione di MediationNativeAdCallback.

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

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