Requisitos previos
Completa la configuración de eventos personalizados.
Solicita un anuncio nativo
Cuando se alcanza la línea de pedido de evento personalizado en la cadena de mediación en cascada, se llama athe loadNativeAd()
method en el nombre de clase que proporcionaste cuando creaste un evento personalizado. En este caso, ese método está en SampleCustomEvent
, que luego llama athe loadNativeAd()
method 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
implementathe Adapter
interface y, luego, 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
es responsable de las siguientes tareas:
Cómo cargar el anuncio nativo
Cómo implementar
UnifiedNativeAdMapper
interfaceCómo recibir devoluciones de llamadas de eventos de anuncios y generar informes al SDK de anuncios de Google para dispositivos móviles
El parámetro opcional definido en la IU de Ad Manager 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 unidades 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 encuentra un error, deberías llamar a onSuccess()
o onFailure()
.
Se llama a onSuccess()
pasando una instancia de la clase que implementa MediationNativeAd
.
Por lo general, estos métodos se implementan dentro de devoluciones de llamada desde el 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)); }
Asigna anuncios nativos
Cada SDK tiene sus propios formatos únicos para los anuncios nativos. Uno podría mostrar objetos que contienen un campo “title”, por ejemplo, mientras que otro podría tener “headline”. Además, los métodos que se usan para hacer un seguimiento de las impresiones y procesar los clics pueden variar de un SDK a otro.
UnifiedNativeAdMapper
se encarga de conciliar estas diferencias y adaptar el objeto de anuncio nativo de un SDK mediado para que coincida con la interfaz que espera el SDK de anuncios de Google para dispositivos móviles. Los eventos personalizados deben extender esta clase para crear sus propios mappers específicos para su SDK mediado. A continuación, se muestra un asignador de anuncios de ejemplo de nuestro proyecto de evento personalizado:
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 con más detalle el código del constructor.
Conserva 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. La clase de asignación necesita una referencia al anuncio mediado para poder pasar eventos de clics e impresiones. SampleNativeAd
se almacena como una variable local.
Cómo establecer propiedades de elementos asignados
El constructor usa el objeto SampleNativeAd
para propagar recursos en UnifiedNativeAdMapper
.
Este fragmento obtiene los datos de precio del anuncio mediado y los usa para establecer el precio del mapeador:
Java
if (sampleAd.getPrice() != null) { NumberFormat formatter = NumberFormat.getCurrencyInstance(); String priceString = formatter.format(sampleAd.getPrice()); setPrice(priceString); }
En este ejemplo, el anuncio mediado almacena el precio como un double
, mientras queAd Manager usa un String
para el mismo recurso. El mapper es responsable de manejar estos tipos de conversiones.
Cómo asignar recursos de imagen
Asignar elementos de imagen es más complicado que asignar tipos de datos, como double
o String
. Las imágenes pueden descargarse automáticamente o mostrarse como valores de URL. Sus escalas de píxeles a DPI también pueden variar.
Para ayudarte a administrar estos detalles, el SDK de anuncios de Google para dispositivos móviles proporciona la clase NativeAd.Image
. Prácticamente de la misma manera que debes crear una subclase de UnifiedNativeAdMapper
para asignar un anuncio nativo mediado, también debes crear una subclase de NativeAd.Image
cuando asignas recursos de imagen.
A continuación, se muestra un ejemplo de 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 la 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));
Agrega campos al paquete de adicionales
Algunos SDK mediados proporcionan elementos adicionales aparte de los que se encuentran en elAd Manager formato del anuncio nativo. La clase UnifiedNativeAdMapper
incluye un método setExtras()
que se usa para pasar estos elementos a los publicadores. El SampleNativeAdMapper
usa esto para el recurso "Grade of awesomeness" del SDK de muestra:
Java
Bundle extras = new Bundle(); extras.putString(SampleCustomEvent.DEGREE_OF_AWESOMENESS, ad.getDegreeOfAwesomeness()); this.setExtras(extras);
Los editores pueden recuperar los datos con el método getExtras()
de la clase NativeAd
.
AdChoices
Tu evento personalizado es responsable de proporcionar un ícono de AdChoices mediante el método setAdChoicesContent()
en UnifiedNativeAdMapper
. A continuación, se muestra un fragmento de SampleNativeAdMapper
en el que se muestra cómo proporcionar el ícono de AdChoices:
Java
public SampleNativeAdMapper(SampleNativeAd ad) { ... setAdChoicesContent(sampleAd.getInformationIcon()); }
Eventos de impresiones y clics
Tanto el SDK de anuncios de Google para dispositivos móviles como el SDK mediado deben saber cuándo se produce una impresión o un clic, pero solo un SDK necesita hacer el seguimiento de estos eventos. Existen dos enfoques diferentes que pueden usar los eventos personalizados, según si el SDK mediado admite el seguimiento de impresiones y clics por su cuenta.
Haz un seguimiento de los clics y las impresiones con el SDK de anuncios de Google para dispositivos móviles
Si el SDK mediado no realiza su propio seguimiento de impresiones y clics, pero proporciona métodos para registrar impresiones y clics, el SDK de Google Mobile Ads puede hacer un seguimiento de estos eventos y notificar al adaptador.UnifiedNativeAdMapper
interface incluye dos métodos:recordImpression()
y handleClick()
que los eventos personalizados pueden implementarse 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); }
Debido a que SampleNativeAdMapper
contiene una referencia al objeto de anuncio nativo del SDK de muestra, puede llamar al método apropiado en ese objeto para informar un clic o una impresión. Ten en cuenta que el método handleClick()
toma un
solo parámetro: el objeto View
que corresponde al recurso de anuncio nativo que
recibió el clic.
Haz un seguimiento de los clics y las impresiones con el SDK mediado
Es posible que algunos SDK mediados prefieran hacer un seguimiento de los clics y las impresiones por su cuenta. En ese caso, debes anular el seguimiento predeterminado de clics e impresiones mediante las siguientes dos llamadas en el constructor de tu UnifiedNativeAdMapper
:
Java
setOverrideClickHandling(true); setOverrideImpressionRecording(true);
Los eventos personalizados que anulan el seguimiento de impresiones y clics deben informar los eventos onAdClicked()
y onAdImpression()
al SDK de anuncios de Google para dispositivos móviles.
Es probable que el SDK mediado necesite acceso a las vistas para habilitar el seguimiento a fin de realizar un seguimiento de las impresiones y los clics. El evento personalizado debe anular el método trackViews()
y usarlo para pasar la vista del anuncio nativo al SDK mediado para su seguimiento. El SDK de muestra de nuestro proyecto de evento personalizado de ejemplo (del que
se tomaron los fragmentos de código de esta guía) no usa este enfoque. Sin embargo, 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 elementos individuales, puede buscar dentro de clickableAssetViews
para ver en qué vistas se debe hacer clic. Este mapa utiliza un nombre de recurso en NativeAdAssetNames
como clave. El objeto UnifiedNativeAdMapper
ofrece un método untrackView()
correspondiente que los eventos personalizados pueden anular para liberar cualquier referencia a la vista y desvincularla del objeto de anuncio nativo.
Reenvía eventos de mediación al SDK de anuncios de Google para dispositivos móviles
Puedes encontrar todas las devoluciones de llamada que admite la mediación en los documentos de MediationNativeAdCallback
.
Es importante que tu evento personalizado reenvíe tantas devoluciones de llamada como sea posible, de modo que tu app reciba estos eventos equivalentes del SDK de anuncios de Google para dispositivos móviles. Este es un ejemplo del uso de devoluciones de llamada:
Con esto, se completa la implementación de eventos personalizados para los anuncios nativos. El ejemplo completo está disponible en GitHub.