Cette page a été traduite par l'API Cloud Translation.

É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,the loadNativeAd() method est appelé sur le nom de classe que vous avez fourni lors de la création d'un événement personnalisé. Dans le cas présent, cette méthode se trouve dans SampleCustomEvent, qui appellethe loadNativeAd() method dans SampleNativeCustomEventLoader.

Pour demander une annonce native, créez ou modifiez une classe qui étend Adapter afin d'implémenter loadNativeAd(). Si une classe qui étend Adapter existe déjà, implémentez loadNativeAd() à cet endroit. En outre, créez une classe pour implémenter UnifiedNativeAdMapper.

Dans notre exemple d'événement personnalisé, SampleCustomEvent implémentethe Adapter interface , 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émenter UnifiedNativeAdMapper interface
Recevoir des rappels d'événements d'annonce et créer des rapports les concernant vers le SDK Google Mobile Ads

Le paramètre facultatif défini dans l'interface utilisateur AdMob est inclus dans la configuration de l'annonce. Ce 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 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 a bien été extraite ou qu'elle rencontre une erreur, vous devez appeler 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 implémenté par votre adaptateur. Pour cet exemple, l'exemple de SDK dispose d'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));
}

Mapper les annonces natives

Chaque SDK possède ses propres formats d'annonces natives. L'un d'entre eux peut par exemple renvoyer des objets contenant un champ "titre", tandis qu'un autre peut avoir un "titre". En outre, les méthodes utilisées pour suivre les impressions et traiter les clics peuvent varier d'un SDK à l'autre.

Le UnifiedNativeAdMapper permet de concilier ces différences et d'adapter l'objet d'annonce native d'un SDK avec médiation pour qu'il corresponde à l'interface attendue par le SDK Google Mobile Ads. Les événements personnalisés doivent étendre cette classe afin de créer leurs propres mappeurs, spécifiques à leur SDK pour la médiation. Voici un exemple d'outil de mappage d'annonces issu 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.
  }
}

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

Conserver une référence à l'objet de l'annonce native faisant l'objet de la 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 mappeur a besoin d'une référence à l'annonce définie pour la médiation afin de 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 insérer les éléments dans UnifiedNativeAdMapper.

Cet extrait récupère les données tarifaires de l'annonce par médiation 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 par médiation stocke le prix en tant que double, tandis qu'AdMob utilise un String pour le même asset. L'outil de mappage est responsable de la gestion de ces types de conversions.

Composants Image de carte

Mettre en correspondance des éléments d'image est plus compliqué 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 d'URL. L'échelle pixel à dpi peut également varier.

Pour vous aider à gérer ces détails, le SDK Google Mobile Ads fournit la classe NativeAd.Image. De la même manière que vous devez 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 des composants Image.

Voici un exemple pour la classe SampleNativeMappedImage de 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 l'élément image d'icône de l'outil de mise en correspondance:

Java

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

Ajouter des champs au bundle "extras"

Certains SDK avec médiation fournissent des assets supplémentaires en plus de ceux duAdMob format d'annonce native. La classe UnifiedNativeAdMapper inclut une méthode setExtras() qui permet de transmettre ces éléments aux éditeurs. SampleNativeAdMapper l'utilise pour l'élément "degré d'excellence" 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.

AdChoices

Votre événement personnalisé doit fournir une icône AdChoices à l'aide de la méthode setAdChoicesContent() sur UnifiedNativeAdMapper. Voici un extrait issu de SampleNativeAdMapper qui montre comment fournir l'icône Choisir sa pub:

Java

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

Événements d'impressions et de clics

Le SDK Google Mobile Ads et le SDK pour la médiation doivent savoir quand une impression ou un clic se produit, mais un seul SDK doit suivre ces événements. Il existe deux approches différentes pour les événements personnalisés, selon que le SDK de médiation prend en charge ou non le suivi des impressions et des clics.

Suivre les clics et les impressions avec le SDK Google Mobile Ads

Si le SDK avec médiation 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.UnifiedNativeAdMapper interface 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 pour la médiation:

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 du SDK Exemple, il peut appeler la méthode appropriée sur cet objet pour signaler un clic ou une impression. Notez que la méthode handleClick() n'utilise qu'un seul paramètre: l'objet View correspondant au composant d'annonce native ayant reçu le clic.

Suivre les clics et les impressions avec le SDK de médiation

Certains SDK avec médiation peuvent préférer effectuer eux-mêmes le suivi des clics et des impressions. Dans ce cas, vous devez remplacer le suivi des clics et des impressions par défaut 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 associé à la médiation a probablement besoin d'accéder aux vues afin d'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 pour la médiation afin qu'il effectue le suivi. L'exemple de SDK de notre exemple de projet d'événement personnalisé (à partir duquel les extraits de code de ce guide ont été extraits) n'utilise pas cette approche. Si tel était le cas, le code de l'événement personnalisé ressemblerait à ceci:

Java

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

Si le SDK de médiation prend en charge le suivi d'éléments individuels, il peut consulter dans clickableAssetViews pour voir les vues à rendre cliquables. Cette carte est associée à 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 native.

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

Vous trouverez tous les rappels compatibles avec la médiation dans la documentation sur MediationNativeAdCallback.

Il est important que votre événement personnalisé transfère autant de rappels que possible, afin que votre application reçoive ces événements équivalents de la part du SDK Google Mobile Ads. Voici un exemple d'utilisation des rappels:

L'implémentation des événements personnalisés pour les annonces natives est maintenant terminée. L'exemple complet est disponible sur GitHub.