Comparte tus comentarios sobre el SDK de GMA de nueva generación en el canal de Discord #gma-next-gen-sdk del servidor de la comunidad de Google Advertising and Measurement.

Eventos personalizados de anuncios nativos

Selecciona la plataforma: Android (beta)

Android iOS

Requisitos previos

Completa la configuración de eventos personalizados.

Cómo solicitar un anuncio nativo

Cuando se alcanza el elemento de línea de evento personalizado en la cadena de mediación en cascada, se llama al método loadNativeAd() en el nombre de la clase que proporcionaste cuando creaste un evento personalizado. En este caso, ese método está en SampleCustomEvent, que luego llama al método loadNativeAd() en SampleNativeCustomEventLoader.

Para solicitar un anuncio nativo, crea o modifica una clase que extienda Adapter para implementar loadNativeAd(). Si ya existe una clase que extiende Adapter, implementa loadNativeAd() allí. Además, crea una clase nueva para implementar UnifiedNativeAdMapper.

En nuestro ejemplo de evento personalizado, SampleCustomEvent extiende la clase Adapter y, luego, 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 es responsable de las siguientes tareas:

Cargar el anuncio nativo
Implementar la clase UnifiedNativeAdMapper
Recibir y registrar devoluciones de llamada de eventos de anuncios en GMA Next-Gen SDK.

El parámetro opcional definido en la IU de AdMob se incluye en la configuración del anuncio. Se puede acceder al parámetro a través de adConfiguration.getServerParameters().getString(MediationConfiguration.CUSTOM_EVENT_SERVER_PARAMETER_FIELD). Por lo general, este parámetro es un identificador de bloque de anuncios que requiere un SDK de red de publicidad cuando se crea una instancia de un objeto de anuncio.

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

Según si el anuncio se recupera correctamente o si se produce un error, tú llamarías a onSuccess() o a onFailure(). Se llama a onSuccess() pasando una instancia de la clase que implementa MediationNativeAd.

Por lo general, estos métodos se implementan dentro de las devoluciones de llamada del SDK de terceros que implementa tu adaptador. Para este ejemplo, el SDK de muestra tiene un SampleAdListener con devoluciones de llamada relevantes:

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

Cómo asignar anuncios nativos

Cada SDK tiene sus propios formatos únicos para los anuncios nativos. Uno podría mostrar objetos que contengan el campo "title", por ejemplo, mientras otro podría tener el campo "headline". Además, es posible que los métodos utilizados para hacer un seguimiento de las impresiones y procesar los clics varíen entre un SDK y otro.

El UnifiedNativeAdMapper es responsable de conciliar estas diferencias y adaptar el objeto de anuncio nativo del SDK mediado para que coincida con la interfaz prevista por GMA Next-Gen SDK. Los eventos personalizados deben extender esta clase para crear sus propios asignadores específicos para su SDK mediado. A continuación, se muestra un asignador de anuncios de muestra de nuestro proyecto de evento personalizado de ejemplo:

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

Ahora, analizaremos más de cerca el código del constructor.

Mantén una referencia al objeto de anuncio nativo mediado

El constructor acepta el parámetro SampleNativeAd, la clase de anuncio nativo que usa el SDK de muestra para sus anuncios nativos. El asignador necesita una referencia al anuncio mediado para poder pasar los eventos de impresiones y clics. SampleNativeAd se almacena como una variable local.

Cómo establecer propiedades de elementos asignados

El constructor usa el SampleNativeAd objeto para propagar recursos en el UnifiedNativeAdMapper.

Este fragmento obtiene los datos de precio del anuncio mediado y los usa para establecer el precio del asignador:

Java

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

En este caso, el anuncio mediado almacena el precio como double, mientras que AdMob usa un String para el mismo recurso. El asignador tiene la función de manejar estos tipos de conversiones.

Cómo asignar elementos de imagen

Asignar recursos de imagen es más complicado que asignar tipos de datos, como double o String. Las imágenes se pueden descargar de forma automática o se pueden mostrar como valores URL. También pueden variar sus escalas de píxeles a dpi.

Para ayudarte a administrar estos detalles, GMA Next-Gen SDK proporciona la NativeAd.Image clase. Así como necesitas crear una subclase de UnifiedNativeAdMapper para asignar un anuncio nativo mediado, también debes crear una subclase de NativeAd.Image cuando asignes recursos de imagen.

A continuación, se muestra un ejemplo para la clase SampleNativeMappedImage del evento personalizado:

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

El SampleNativeAdMapper usa su clase de imagen asignada en esta línea para establecer el recurso de imagen de ícono del asignador:

Java

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

Cómo agregar campos al paquete de adicionales

Algunos SDKs mediados proporcionan recursos adicionales aparte de los que se encuentran en el formato de anuncios nativos de AdMob. La UnifiedNativeAdMapper clase incluye un método setExtras() que se usa para pasar estos recursos a los publicadores. El SampleNativeAdMapper usa esto para el recurso "nivel de genialidad" del SDK de Sample:

Java

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

Los publicadores pueden recuperar los datos con el getExtras() método de la clase NativeAd.

AdChoices

Tu evento personalizado es responsable de proporcionar un ícono de AdChoices con el setAdChoicesContent() método en UnifiedNativeAdMapper. Este es un fragmento de SampleNativeAdMapper que muestra cómo proporcionar el ícono de AdChoices:

Java

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

Eventos de impresiones y clics

Tanto GMA Next-Gen SDK como el SDK mediado necesitan saber cuándo se produce una impresión o un clic, pero solo uno de los ellos necesita hacer un seguimiento de estos eventos. Los eventos personalizados pueden usar dos enfoques diferentes según si el SDK mediado admite el seguimiento de las impresiones y los clics por su cuenta.

Haz un seguimiento de los clics y las impresiones con GMA Next-Gen SDK

Si el SDK mediado no realiza su propio seguimiento de impresiones y clics, pero proporciona métodos para registrar estos eventos, GMA Next-Gen SDK puede hacer un seguimiento de ellos y notificar al adaptador. La UnifiedNativeAdMapper clase incluye dos métodos: recordImpression() y handleClick() que los eventos personalizados pueden implementar para llamar al método correspondiente en el objeto de anuncio nativo mediado:

Java

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

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

Dado que SampleNativeAdMapper contiene una referencia al objeto de anuncio nativo del SDK de muestra, puede llamar al método adecuado en ese objeto para registrar un clic o una impresión. Ten en cuenta que el método handleClick() tiene un solo parámetro, que es el objeto View correspondiente al recurso del anuncio nativo que recibió el clic.

Haz un seguimiento de los clics y las impresiones con el SDK mediado

Es posible que algunos SDKs mediados prefieran hacer un seguimiento de los clics y las impresiones por su cuenta. En ese caso, debes anular el seguimiento predeterminado de impresiones y clics realizando las siguientes dos llamadas en el constructor de tu UnifiedNativeAdMapper:

Java

setOverrideClickHandling(true);
setOverrideImpressionRecording(true);

Los eventos personalizados que anulan el seguimiento de clics e impresiones deben informar los eventos onAdClicked() y onAdImpression() al SDK de anuncios de Google para dispositivos móviles.

Para hacer un seguimiento de las impresiones y los clics, es probable que el SDK mediado necesite acceso a las vistas para habilitar el seguimiento. El evento personalizado debe anular el trackViews() método y usarlo para pasar la vista del anuncio nativo al SDK mediado para realizar el seguimiento. El SDK de muestra de nuestro proyecto de ejemplo de evento personalizado (del que se tomaron los fragmentos de código de esta guía) no usa este enfoque, pero, si lo hiciera, el código del evento personalizado se vería de la siguiente manera:

Java

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

Si el SDK mediado admite el seguimiento de recursos individuales, puede consultar clickableAssetViews para ver en qué vistas se debe poder hacer clic. Este mapa se indexa por un nombre de recurso en NativeAdAssetNames. El UnifiedNativeAdMapper ofrece un método untrackView() correspondiente que los eventos personalizados pueden anular para liberar cualquier referencia a la vista y disociarla del objeto del anuncio nativo.

Reenvía eventos de mediación a GMA Next-Gen SDK

Puedes encontrar todas las devoluciones de llamada que admite la mediación en los MediationNativeAdCallback documentos.

Es importante que tu evento personalizado reenvíe la mayor cantidad posible de estas devoluciones de llamada para que tu app reciba estos eventos equivalentes de GMA Next-Gen SDK. A continuación, se muestra un ejemplo del uso de devoluciones de llamada:

Con esto, se completa la implementación de eventos personalizados para anuncios nativos. El ejemplo completo está disponible en GitHub.

Eventos personalizados de anuncios nativos Organiza tus páginas con colecciones Guarda y categoriza el contenido según tus preferencias.

Requisitos previos

Cómo solicitar un anuncio nativo

Java

Java

Java

Cómo asignar anuncios nativos

Java

Mantén una referencia al objeto de anuncio nativo mediado

Cómo establecer propiedades de elementos asignados

Java

Cómo asignar elementos de imagen

Java

Java

Cómo agregar campos al paquete de adicionales

Java

AdChoices

Java

Eventos de impresiones y clics

Haz un seguimiento de los clics y las impresiones con GMA Next-Gen SDK

Java

Haz un seguimiento de los clics y las impresiones con el SDK mediado

Java

Java

Reenvía eventos de mediación a GMA Next-Gen SDK

Eventos personalizados de anuncios nativos