Événements personnalisés pour les annonces natives

Prérequis

Terminez la configuration des événements personnalisés.

Demander une annonce native

Lorsque l'élément de campagne d'événement personnalisé est atteint dans la chaîne de médiation en cascade, la méthode loadNativeAd() est appelée sur le nom de classe que vous avez fourni lorsque la création d'un l'événement. 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 à implémenter loadNativeAd(). Si une classe qui étend Adapter existe déjà, pour implémenter loadNativeAd(). Créez également une classe à implémenter UnifiedNativeAdMapper

Dans notre exemple d'événement personnalisé, SampleCustomEvent étend la classe Adapter, puis délègue à SampleNativeCustomEventLoader

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émentez la classe UnifiedNativeAdMapper.

• Recevoir des rappels d'événements d'annonce et les signaler au SDK Google Mobile Ads

Le paramètre facultatif défini dans l'interface utilisateur d'Ad Manager est dans la configuration de l'annonce. Le paramètre est accessible via adConfiguration.getServerParameters().getString(MediationConfiguration.CUSTOM_EVENT_SERVER_PARAMETER_FIELD) Il s'agit généralement d'un identifiant de bloc d'annonces qu'un SDK de réseau publicitaire requis lors de l'instanciation d'un objet d'annonce.

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 a bien été récupérée ou rencontre une erreur, vous appellerait soit 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 des rappels à partir de la méthode par un SDK tiers implémenté par votre adaptateur. Dans cet exemple, l'exemple de SDK comporte un SampleAdListener avec les rappels appropriés:

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

Mettre en correspondance les annonces natives

Chaque SDK possède son propre format propre aux annonces natives. On pourrait revenir Objets contenant un "titre" par exemple, tandis qu'un autre champ peut contenir "headline". En outre, les méthodes de suivi des impressions et de traitement les clics peuvent varier d'un SDK à l'autre.

Le UnifiedNativeAdMapper est chargé de concilier ces différences et d'adapter l'objet d'annonce native d'un SDK à médiation pour qu'il corresponde à l'interface attendue le SDK Google Mobile Ads. Les événements personnalisés devraient étendre cette classe pour créer leurs propres mappeurs spécifiques à leur SDK avec médiation. Voici un exemple de Ad Mapper notre exemple de projet d'événement personnalisé:

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

Examinons maintenant de plus près le code du constructeur.

Contient une référence à l'objet d'annonce native par médiation

Le constructeur accepte le paramètre SampleNativeAd, la classe d'annonce native utilisée par l'exemple de SDK pour ses annonces natives. Le cartographe a besoin d'une référence au par médiation pour pouvoir transmettre des événements de clic et d'impression. SampleNativeAd correspond à stockée 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 la UnifiedNativeAdMapper

Cet extrait récupère les données tarifaires de l'annonce par médiation et les utilise pour définir price [prix] :

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

Dans cet exemple, l'annonce par médiation stocke le prix sous la forme d'un double, tandis que Ad Manager utilise un String pour le même élément. La mapper est responsable de la gestion de ces types de conversions.

Composants Image de la carte

Il est plus compliqué de mapper des éléments image que de mapper 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. Leur échelle de pixel à ppp peut également varier.

Pour vous aider à gérer ces informations, le SDK Google Mobile Ads fournit NativeAd.Image. De la même manière que pour créer une sous-classe, de UnifiedNativeAdMapper pour mapper une annonce native par médiation, vous devez également créer une sous-classe de NativeAd.Image lors du mappage d'éléments image.

Voici un exemple pour la classe SampleNativeMappedImage de l'événement personnalisé:

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 élément image de l'icône de cartographe:

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

Ajouter des champs au bundle d'extras

Certains SDK associés à la médiation fournissent des assets supplémentaires en plus de ceux inclus dans le le format d'annonce native Ad Manager. UnifiedNativeAdMapper inclut une méthode setExtras() qui permet de transmettre ces éléments aux éditeurs. SampleNativeAdMapper l'utilise pour les exemples de SDK "degré de génial" actif:

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 classe NativeAd. getExtras() .

Choisir sa pub

Votre événement personnalisé doit fournir une icône Choisir sa pub à l'aide de l'événement setAdChoicesContent() sur UnifiedNativeAdMapper. Voici un extrait de SampleNativeAdMapper montrant comment fournir l'icône Choisir sa pub:

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

Événements d'impression et de clic

Le SDK Google Mobile Ads et le SDK avec médiation doivent savoir quand un une impression ou un clic, mais un seul SDK doit les suivre. Il y sont deux approches différentes pour les événements personnalisés, selon le SDK de médiation permet lui-même de suivre les impressions et les clics.

Effectuer le suivi des clics et des impressions avec le SDK Google Mobile Ads

Si le SDK associé à la médiation n'effectue pas son propre suivi des impressions et des clics, propose des méthodes pour enregistrer les clics et les impressions, le SDK Google Mobile Ads suivre ces événements et en informer l'adaptateur. La La classe UnifiedNativeAdMapper comprend deux méthodes: recordImpression() et handleClick() qui les événements personnalisés peuvent être implémentés pour appeler la méthode correspondante sur le objet d'annonce native:

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

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

Comme SampleNativeAdMapper contient une référence au code natif de l'exemple de SDK l'objet d'annonce, il peut appeler la méthode appropriée sur cet objet pour signaler un clic ou impression. Notez que la méthode handleClick() prend une Paramètre unique: objet View correspondant au composant d'annonce native a reçu le clic.

Suivre les clics et les impressions avec le SDK pour la médiation

Certains SDK avec médiation peuvent préférer suivre les clics et les impressions eux-mêmes. Dans Dans ce cas, vous devez remplacer le suivi par défaut des clics et des impressions effectuer les deux appels suivants dans le constructeur de votre UnifiedNativeAdMapper:

setOverrideClickHandling(true);
setOverrideImpressionRecording(true);

Les événements personnalisés qui ignorent le suivi des clics et des impressions sont requis pour signaler les événements onAdClicked() et onAdImpression() à l'application SDK Ads.

Pour effectuer le suivi des impressions et des clics, le SDK associé à la médiation a probablement besoin d'accéder à la pour activer le suivi. L'événement personnalisé doit remplacer trackViews() et utilisez-la pour transmettre la vue de l'annonce native à la méthode de médiation. SDK à suivre. L'exemple de SDK de notre projet d'exemple d'événement personnalisé (à partir duquel les extraits de code de ce guide ont déjà été suivis) n'utilise pas cette approche. mais si le code de l'événement personnalisé ressemblerait à ceci:

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

Si le SDK associé à la médiation permet de suivre des éléments individuels, il peut examiner clickableAssetViews pour voir les vues qui doivent être cliquables. Cette carte est associé à un nom d'élément dans NativeAdAssetNames. UnifiedNativeAdMapper propose une méthode untrackView() correspondante que les événements personnalisés peuvent remplacer afin de libérer toute référence à la vue et de la dissocier de l'annonce native. .

Transférer les événements de médiation au SDK Google Mobile Ads

Vous trouverez tous les rappels compatibles avec la médiation dans le Documentation sur MediationNativeAdCallback

Il est important que votre événement personnalisé transfère autant de rappels que vous le souhaitez afin que votre application reçoive ces événements équivalents SDK Mobile Ads. Voici un exemple d'utilisation des rappels:

Cette opération termine l'implémentation des événements personnalisés pour les annonces natives. Exemple complet est disponible sur GitHub