Prerequisiti
Completa la configurazione degli eventi personalizzati.
Richiedere un annuncio nativo
Quando viene raggiunto l'elemento pubblicitario evento personalizzato nella catena di mediazione a cascata, viene chiamato il metodo loadNativeAd()
con il nome della classe che hai fornito durante la creazione di un evento personalizzato. In questo caso, il metodo si trova in SampleCustomEvent
, che chiama il metodo loadNativeAd()
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()
al suo interno. Inoltre, crea un nuovo corso per implementareUnifiedNativeAdMapper
.
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
.Ricevere e segnalare i callback degli eventi correlati agli annunci all'SDK Google Mobile Ads.
Il parametro facoltativo definito nell'interfaccia utente di Ad Manager è incluso nella configurazione dell'annuncio. È possibile accedere al parametro tramite
adConfiguration.getServerParameters().getString(MediationConfiguration.CUSTOM_EVENT_SERVER_PARAMETER_FIELD)
.
In genere, questo parametro è un identificatore dell'unità pubblicitaria richiesto da un SDK della rete pubblicitaria quando viene creata 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 se si verifica un errore, chiama
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 Sample ha un SampleAdListener
con i 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 della scheda
I diversi SDK hanno formati unici per gli annunci nativi. Uno potrebbe restituire oggetti contenenti un campo "title", ad esempio, mentre un altro potrebbe avere "headline". Inoltre, i metodi utilizzati per monitorare le impressioni e 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 mediato in modo che corrisponda all'interfaccia prevista dall'SDK Google Mobile Ads. Gli eventi personalizzati devono estendere questa classe per creare i propri mapper specifici per l'SDK mediato. Ecco un mapper degli annunci di esempio 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.
Contiene un riferimento all'oggetto dell'annuncio nativo mediato
Il costruttore accetta il parametro SampleNativeAd
, la classe di annunci nativi utilizzata dall'SDK di Sample per i suoi annunci nativi. Il mapper ha bisogno di un riferimento all'annuncio mediato per poter trasmettere gli eventi di clic e di impressione. SampleNativeAd
viene memorizzato come variabile locale.
Impostare 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 mediato 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 mediato memorizza il prezzo come double
, mentre Ad Manager utilizza un String
per lo stesso asset. Il mapper è responsabile della gestione di questi tipi di conversioni.
Mappa gli asset immagine
La mappatura degli asset immagine è più complicata della mappatura dei tipi di dati come
double
o String
. Le immagini potrebbero essere scaricate automaticamente o
rese 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
. In modo simile a come devi creare una sottoclasse di UnifiedNativeAdMapper
per mappare un annuncio nativo mediato, devi anche creare una sottoclasse di UnifiedNativeAdMapper
quando mappi gli asset immagine.NativeAd.Image
Di seguito è riportato 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 immagine mappata in questa riga per impostare l'asset immagine icona del mapper:
Java
setIcon(new SampleNativeMappedImage(ad.getAppIcon(), ad.getAppIconUri(), SampleCustomEvent.SAMPLE_SDK_IMAGE_SCALE));
Aggiungere campi al pacchetto di extra
Alcuni SDK mediati forniscono asset aggiuntivi oltre a quelli nel formato dell'annuncio nativo di Ad Manager. La classe UnifiedNativeAdMapper
include un metodo setExtras()
che viene utilizzato per passare questi asset ai publisher. SampleNativeAdMapper
ne fa uso per l'asset "grado di eccellenza" 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 di fornire un'icona Scegli Tu! utilizzando il metodo setAdChoicesContent()
su UnifiedNativeAdMapper
. Ecco uno snippet diSampleNativeAdMapper
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 sia l'SDK mediato devono sapere quando si verifica un'impressione o un clic, ma solo un SDK deve monitorare questi eventi. Gli eventi personalizzati possono utilizzare due approcci diversi, a seconda che l'SDK mediato supporti o meno il monitoraggio delle impressioni e dei clic autonomamente.
Monitorare i clic e le impressioni con l'SDK Google Mobile Ads
Se l'SDK mediato non esegue il proprio monitoraggio delle impressioni e dei clic, ma fornisce metodi per registrare clic e impressioni, l'SDK Google Mobile Ads 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 annunci
nativo mediato:
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 di Sample, 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.
Monitorare i clic e le impressioni con l'SDK mediato
Alcuni SDK mediati potrebbero preferire monitorare i clic e le impressioni autonomamente. In questo caso, devi sostituire il monitoraggio dei clic e delle impressioni predefinito effettuando le due chiamate seguenti nel costruttore di UnifiedNativeAdMapper
:
Java
setOverrideClickHandling(true); setOverrideImpressionRecording(true);
Gli eventi personalizzati che sostituiscono il monitoraggio dei clic e delle impressioni sono obbligatori per registrare gli eventi onAdClicked()
e onAdImpression()
nell'SDK Google Mobile Ads.
Per monitorare le impressioni e i clic, l'SDK mediato probabilmente ha bisogno di accedere alle visualizzazioni per attivare il monitoraggio. L'evento personalizzato deve sostituire il metodo
trackViews()
e utilizzarlo per passare la visualizzazione dell'annuncio nativo all'SDK mediato da monitorare. L'SDK di esempio del nostro progetto di esempio di evento personalizzato (da cui sono stati estratti gli snippet di codice di questa guida) non utilizza questo approccio, ma se lo facesse, il codice evento personalizzato avrebbe il seguente aspetto:
Java
@Override public void trackViews(View containerView, Map<String, View> clickableAssetViews, Map<String, View> nonClickableAssetViews) { sampleAd.setNativeAdViewForTracking(containerView); }
Se l'SDK mediato supporta il monitoraggio dei singoli asset, può esaminareclickableAssetViews
per vedere quali visualizzazioni devono essere rese cliccabili. Questa mappa è basata su un nome asset in NativeAdAssetNames
. UnifiedNativeAdMapper
offre un metodo untrackView()
corrispondente che gli eventi personalizzati possono eseguire l'override per rilasciare eventuali riferimenti alla visualizzazione e disaccoppiarla dall'oggetto annuncio nativo.
Inoltra 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 l'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.