Prérequis
Terminez la configuration des événements personnalisés.
Demander une annonce native
Lorsque l'élément de ligne de l'événement personnalisé est atteint dans la chaîne de médiation en cascade, la méthode loadNativeAd()
est appelée avec le nom de classe que vous avez fourni lors de la création d'un événement personnalisé. Dans ce cas, cette méthode se trouve dans SampleCustomEvent
, qui appelle ensuite la méthode loadNativeAd()
dans SampleNativeCustomEventLoader
.
Pour demander une annonce native, créez ou modifiez une classe qui étend Adapter
pour implémenter loadNativeAd()
. Si une classe qui étend Adapter
existe déjà, implémentez loadNativeAd()
. En outre, créez une classe pour implémenter UnifiedNativeAdMapper
.
Dans notre exemple d'événement personnalisé, SampleCustomEvent
étend la classe Adapter
, puis délègue à 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
est responsable des tâches suivantes:
Chargement de l'annonce native.
Implémentation de la classe
UnifiedNativeAdMapper
.Recevoir et signaler les rappels d'événements d'annonce au SDK Google Mobile Ads
Le paramètre facultatif défini dans l'interface utilisateur AdMob est inclus dans la configuration de l'annonce. Le paramètre est accessible via adConfiguration.getServerParameters().getString(MediationConfiguration.CUSTOM_EVENT_SERVER_PARAMETER_FIELD)
.
Ce paramètre est généralement un identifiant de bloc d'annonces requis par un SDK de réseau publicitaire lors de l'instanciation d'un objet d'annonce.
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); } }
Selon que l'annonce est récupérée avec succès ou qu'une erreur se produit, appelez onSuccess()
ou onFailure()
.
onSuccess()
est appelé en transmettant une instance de la classe qui implémente MediationNativeAd
.
En règle générale, ces méthodes sont implémentées dans les rappels du SDK tiers que votre adaptateur implémente. Pour cet exemple, l'exemple de SDK possède un SampleAdListener
avec des rappels pertinents:
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)); }
Annonces natives sur la carte
Les différents SDK ont leurs propres formats d'annonces natives. L'un peut renvoyer des objets contenant un champ "titre", par exemple, tandis qu'un autre peut avoir "titre". De plus, les méthodes utilisées pour suivre les impressions et traiter les clics peuvent varier d'un SDK à l'autre.
UnifiedNativeAdMapper
est chargé de concilier ces différences et d'adapter l'objet d'annonce native d'un SDK médiatisé pour qu'il corresponde à l'interface attendue par le SDK Google Mobile Ads. Les événements personnalisés doivent étendre cette classe pour créer leurs propres mappeurs spécifiques à leur SDK médiatisé. Voici un exemple de mappeur d'annonces de notre exemple de projet d'événement personnalisé:
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. } }
Nous allons maintenant examiner de plus près le code du constructeur.
Maintenir une référence à l'objet d'annonce native médiatisée
Le constructeur accepte le paramètre SampleNativeAd
, la classe d'annonces natives utilisée par le SDK Sample pour ses annonces natives. Le mappeur a besoin d'une référence à l'annonce médiatisée pour pouvoir transmettre les événements de clic et d'impression. SampleNativeAd
est stocké en tant que variable locale.
Définir les propriétés des éléments mappés
Le constructeur utilise l'objet SampleNativeAd
pour renseigner les éléments dans le UnifiedNativeAdMapper
.
Cet extrait récupère les données de prix de l'annonce médiatisée et les utilise pour définir le prix du mappeur:
Java
if (sampleAd.getPrice() != null) { NumberFormat formatter = NumberFormat.getCurrencyInstance(); String priceString = formatter.format(sampleAd.getPrice()); setPrice(priceString); }
Dans cet exemple, l'annonce médiatisée stocke le prix en tant que double
, tandis qu'AdMob utilise un String
pour le même composant. Le mappeur est chargé de gérer ces types de conversions.
Composants Image de la carte
Le mappage des éléments Image est plus complexe que le mappage des types de données tels que double
ou String
. Les images peuvent être téléchargées automatiquement ou renvoyées sous forme de valeurs d'URL. Leurs échelles de pixels en dpi peuvent également varier.
Pour vous aider à gérer ces informations, le SDK Google Mobile Ads fournit la classe NativeAd.Image
. Tout comme vous devez créer une sous-classe de UnifiedNativeAdMapper
pour mapper une annonce native médiatisée, vous devez également créer une sous-classe de NativeAd.Image
lorsque vous mappez des composants Image.
Voici un exemple de classe SampleNativeMappedImage
pour l'événement personnalisé:
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
utilise sa classe d'image mappée dans cette ligne pour définir le composant d'image d'icône du mappeur:
Java
setIcon(new SampleNativeMappedImage(ad.getAppIcon(), ad.getAppIconUri(), SampleCustomEvent.SAMPLE_SDK_IMAGE_SCALE));
Ajouter des champs au bundle d'extras
Certains SDK de médiation fournissent des composants supplémentaires en plus de ceux du format d'annonce native AdMob. La classe UnifiedNativeAdMapper
inclut une méthode setExtras()
qui permet de transmettre ces éléments aux éditeurs. SampleNativeAdMapper
s'en sert pour l'élément "degrés de génialité" du SDK d'exemple:
Java
Bundle extras = new Bundle(); extras.putString(SampleCustomEvent.DEGREE_OF_AWESOMENESS, ad.getDegreeOfAwesomeness()); this.setExtras(extras);
Les éditeurs peuvent récupérer les données à l'aide de la méthode getExtras()
de la classe NativeAd
.
Choisir sa pub
Votre événement personnalisé est chargé de fournir une icône Choisir sa pub à l'aide de la méthode setAdChoicesContent()
sur UnifiedNativeAdMapper
. Voici un extrait de SampleNativeAdMapper
montrant comment fournir l'icône Choisir sa pub:
Java
public SampleNativeAdMapper(SampleNativeAd ad) { ... setAdChoicesContent(sampleAd.getInformationIcon()); }
Événements d'impression et de clic
Le SDK Google Mobile Ads et le SDK de médiation doivent savoir quand une impression ou un clic se produit, mais un seul SDK doit suivre ces événements. Les événements personnalisés peuvent utiliser deux approches différentes, selon que le SDK de médiation permet ou non de suivre les impressions et les clics.
Suivre les clics et les impressions avec le SDK Google Mobile Ads
Si le SDK médiatisé n'effectue pas son propre suivi des impressions et des clics, mais fournit des méthodes pour enregistrer les clics et les impressions, le SDK Google Mobile Ads peut suivre ces événements et en informer l'adaptateur. La classe UnifiedNativeAdMapper
inclut deux méthodes : recordImpression()
et handleClick()
que les événements personnalisés peuvent implémenter pour appeler la méthode correspondante sur l'objet d'annonce native médiatisée:
Java
@Override public void recordImpression() { sampleAd.recordImpression(); } @Override public void handleClick(View view) { sampleAd.handleClick(view); }
Étant donné que SampleNativeAdMapper
contient une référence à l'objet d'annonce native de l'exemple de SDK, il peut appeler la méthode appropriée sur cet objet pour signaler un clic ou une impression. Notez que la méthode handleClick()
utilise un seul paramètre: l'objet View
correspondant à l'asset d'annonce natif ayant reçu le clic.
Suivre les clics et les impressions avec le SDK de médiation
Certains SDK de médiation peuvent préférer suivre eux-mêmes les clics et les impressions. Dans ce cas, vous devez remplacer le suivi par défaut des clics et des impressions en effectuant les deux appels suivants dans le constructeur de votre UnifiedNativeAdMapper
:
Java
setOverrideClickHandling(true); setOverrideImpressionRecording(true);
Les événements personnalisés qui remplacent le suivi des clics et des impressions sont nécessaires pour signaler les événements onAdClicked()
et onAdImpression()
au SDK Google Mobile Ads.
Pour suivre les impressions et les clics, le SDK de médiation a probablement besoin d'accéder aux vues pour activer le suivi. L'événement personnalisé doit remplacer la méthode trackViews()
et l'utiliser pour transmettre la vue de l'annonce native au SDK médiatisé à des fins de suivi. L'exemple de SDK de notre projet d'exemple d'événement personnalisé (à partir duquel les extraits de code de ce guide ont été extraits) n'utilise pas cette approche. Toutefois, si c'était le cas, le code de l'événement personnalisé se présenterait comme suit:
Java
@Override public void trackViews(View containerView, Map<String, View> clickableAssetViews, Map<String, View> nonClickableAssetViews) { sampleAd.setNativeAdViewForTracking(containerView); }
Si le SDK de médiation est compatible avec le suivi d'éléments individuels, il peut examiner clickableAssetViews
pour voir quelles vues doivent être cliquables. Ce mappage est associé à un nom d'élément dans NativeAdAssetNames
. UnifiedNativeAdMapper
propose une méthode untrackView()
correspondante que les événements personnalisés peuvent remplacer pour libérer toutes les références à la vue et la dissocier de l'objet d'annonce natif.
Transmettre les événements de médiation au SDK Google Mobile Ads
Vous trouverez tous les rappels compatibles avec la médiation dans la documentation MediationNativeAdCallback
.
Il est important que votre événement personnalisé transfère autant de ces rappels que possible afin que votre application reçoive ces événements équivalents du SDK Google Mobile Ads. Voici un exemple d'utilisation de rappels:
L'implémentation des événements personnalisés pour les annonces natives est terminée. L'exemple complet est disponible sur GitHub.