Google utilizza la tecnologia AI per tradurre i contenuti nella tua lingua preferita. Le traduzioni generate dall'AI potrebbero contenere errori.

Eventi personalizzati di annunci nativi

Seleziona la piattaforma: Android iOS Android (Legacy)

Prerequisiti

Completa la configurazione degli eventi personalizzati.

Richiedi un annuncio nativo

Quando l'elemento pubblicitario dell'evento personalizzato viene raggiunto nella catena di mediazione a cascata, il metodo loadNativeAd() viene chiamato sul nome classe fornito durante la creazione di un evento personalizzato. In questo caso, il metodo si trova in SampleCustomEvent, che poi chiama il metodo loadNativeAd() in SampleNativeCustomEventLoader.

Per richiedere un annuncio nativo, crea o modifica una classe che estende 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 estende la classe Adapter e poi delega a 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 è responsabile delle seguenti attività:

Caricamento dell'annuncio nativo.
Implementazione della classe UnifiedNativeAdMapper.
Ricezione e segnalazione dei callback degli eventi degli annunci a GMA Next-Gen SDK.

Il parametro facoltativo definito nell'UI di AdMob è incluso nella configurazione dell'annuncio. Il parametro è accessibile tramite adConfiguration.getServerParameters().getString(MediationConfiguration.CUSTOM_EVENT_SERVER_PARAMETER_FIELD). Questo parametro è in genere un identificatore dell'unità pubblicitaria richiesto dall'SDK di una rete pubblicitaria durante la creazione di un'istanza di un oggetto 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, devi 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 dall'adattatore. Per questo esempio, l'SDK di esempio ha un 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));
}

Annunci nativi di Maps

SDK diversi hanno formati unici per gli annunci nativi. Ad esempio, uno potrebbe restituire oggetti che contengono un campo "title", mentre un altro potrebbe avere "headline". Inoltre, i metodi utilizzati per monitorare le impressioni ed elaborare i clic possono variare da un SDK all'altro.

UnifiedNativeAdMapper è responsabile della riconciliazione di queste differenze e dell'adattamento dell'oggetto annuncio nativo di un SDK con mediazione in modo che corrisponda all'interfaccia prevista da GMA Next-Gen SDK. Gli eventi personalizzati devono estendere questa classe per creare i propri mapper specifici per l'SDK di mediazione. Ecco un esempio di mappatore di annunci del nostro progetto di eventi personalizzati 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 esaminiamo più da vicino il codice del costruttore.

Mantieni 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 mapper ha bisogno di un riferimento all'annuncio con mediazione per poter trasmettere gli eventi di clic e impressione. SampleNativeAd viene archiviata come variabile locale.

Imposta le proprietà degli asset mappati

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

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

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

Asset immagine mappa

La mappatura degli asset immagine è più complessa di quella di tipi di dati come double o String. Le immagini potrebbero essere scaricate automaticamente o restituite come valori URL. Anche le scale da pixel a DPI possono variare.

Per aiutarti a gestire questi dettagli, GMA Next-Gen SDK fornisce la classe NativeAd.Image. Analogamente a come devi creare una sottoclasse di UnifiedNativeAdMapper per mappare un annuncio nativo con mediazione, devi anche creare una sottoclasse di NativeAd.Image quando mappi gli 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 classe di immagini mappate in questa riga per impostare l'asset immagine dell'icona del mapper:

Java

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

Aggiungi campi al bundle di extra

Alcuni SDK con mediazione forniscono asset aggiuntivi rispetto a quelli del formato dell'annuncio nativo AdMob. La classe UnifiedNativeAdMapper include un metodo setExtras() utilizzato per trasmettere questi asset ai publisher. SampleNativeAdMapper utilizza questo elemento per l'asset "degree of awesomeness" dell'SDK di esempio:

Java

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

I publisher possono recuperare i dati utilizzando il metodo getExtras() della classe NativeAd.

Scegli Tu!

L'evento personalizzato è responsabile della visualizzazione di 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 impressione e di clic

Sia GMA Next-Gen SDK sia l'SDK di mediazione devono sapere quando si verifica un'impressione o un clic, ma solo un SDK deve monitorare questi eventi. Esistono due approcci diversi che gli eventi personalizzati possono utilizzare, a seconda che l'SDK con mediazione supporti o meno il monitoraggio di impressioni e clic.

Monitora i clic e le impressioni con GMA Next-Gen SDK

Se l'SDK con mediazione non esegue il proprio monitoraggio delle impressioni e dei clic, ma fornisce metodi per registrare clic e impressioni, GMA Next-Gen SDK può monitorare questi eventi e inviare una notifica all'adattatore. La classe UnifiedNativeAdMapper include due metodi: recordImpression() e handleClick() che gli eventi personalizzati possono implementare per chiamare il metodo corrispondente sull'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 dell'annuncio nativo dell'SDK di esempio, può chiamare il metodo appropriato su quell'oggetto per segnalare un clic o un'impressione. Tieni presente che il metodo handleClick() accetta un singolo parametro: l'oggetto View corrispondente all'asset annuncio nativo che ha ricevuto il clic.

Monitora i clic e le impressioni con l'SDK con mediazione

Alcuni SDK con mediazione potrebbero preferire monitorare i clic e le impressioni in autonomia. In questo caso, devi eseguire l'override del monitoraggio predefinito di clic e tracker delle impressioni effettuando le seguenti due chiamate nel costruttore di UnifiedNativeAdMapper:

Java

setOverrideClickHandling(true);
setOverrideImpressionRecording(true);

Gli eventi personalizzati che eseguono l'override del monitoraggio dei clic e delle impressioni devono segnalare gli eventi onAdClicked() e onAdImpression() all'SDK Google Mobile Ads.

Per monitorare le impressioni e i clic, l'SDK con mediazione probabilmente deve accedere alle visualizzazioni per attivare il monitoraggio. L'evento personalizzato deve eseguire l'override del metodo trackViews() e utilizzarlo per passare la visualizzazione dell'annuncio nativo all'SDK con mediazione per il monitoraggio. L'SDK di esempio del nostro progetto di esempio di evento personalizzato (da cui sono stati presi gli snippet di codice di questa guida) non utilizza questo approccio, ma se lo facesse, il codice dell'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 dei singoli asset, può esaminare clickableAssetViews per vedere quali visualizzazioni devono essere rese cliccabili. Questa mappa è indicizzata in base al nome di un asset in NativeAdAssetNames. UnifiedNativeAdMapper offre un metodo untrackView() corrispondente che gli eventi personalizzati possono sostituire per rilasciare eventuali riferimenti alla visualizzazione e dissociarla dall'oggetto dell'annuncio nativo.

Inoltra gli eventi di mediazione a GMA Next-Gen SDK

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 l'app riceva questi eventi equivalenti da GMA Next-Gen SDK. Ecco un esempio di utilizzo dei callback:

In questo modo, l'implementazione degli eventi personalizzati per gli annunci nativi è completa. L'esempio completo è disponibile su GitHub.

Eventi personalizzati di annunci nativi Mantieni tutto organizzato con le raccolte Salva e classifica i contenuti in base alle tue preferenze.

Prerequisiti

Richiedi un annuncio nativo

Java

Java

Java

Annunci nativi di Maps

Java

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

Imposta le proprietà degli asset mappati

Java

Asset immagine mappa

Java

Java

Aggiungi campi al bundle di extra

Java

Scegli Tu!

Java

Eventi di impressione e di clic

Monitora i clic e le impressioni con GMA Next-Gen SDK

Java

Monitora i clic e le impressioni con l'SDK con mediazione

Java

Java

Inoltra gli eventi di mediazione a GMA Next-Gen SDK

Eventi personalizzati di annunci nativi