Développement d'un adaptateur d'enchères

Ce guide s'adresse aux réseaux publicitaires qui souhaitent créer un adaptateur d'enchères pour participer aux enchères en temps réel (RTB) dans la médiation Google. Si vous êtes éditeur, consultez les instructions concernant la médiation pour les éditeurs.

Un adaptateur d'enchères est la partie côté client de l'intégration. L'adaptateur permet au SDK de votre réseau publicitaire de communiquer avec le SDK Google Mobile Ads pour charger les annonces diffusées par votre enchérisseur.

Pour que les enchères fonctionnent correctement, votre adaptateur devra gérer l'initialisation, la collecte des signaux, le chargement des annonces et la transmission des événements du cycle de vie des annonces. Dans ce guide, nous vous expliquerons comment implémenter votre adaptateur pour gérer ces opérations.

Remarque : Pour participer aux enchères, vous devez également disposer d'un enchérisseur capable de répondre aux demandes OpenRTB. Les instructions sur la façon de configurer un enchérisseur ne sont pas traitées dans ce guide.

Workflow d'un adaptateur d'enchères

Initialisation

Vous trouverez ci-dessous un flux détaillé du cycle de vie complet de la requête, de la réponse et du rendu d'un adaptateur :

L'adaptateur est responsable des parties suivantes du workflow :

• Étapes 4 à 7 : Initialisez votre adaptateur et rappelez le SDK Google Mobile Ads une fois l'initialisation terminée.

• Étapes 10 à 13 : Collectez les signaux du SDK de votre réseau publicitaire à envoyer à votre enchérisseur pour participer à une demande RTB, puis transmettez-les au SDK Google Mobile Ads.

• Étapes 18 à 21 : Si votre système d'enchères renvoie l'enchère gagnante, chargez l'annonce en fonction de la réponse de votre système d'enchères. Une fois l'annonce chargée, informez le SDK Google Mobile Ads qu'elle l'a été.

• Étape 23 et ultérieures : pendant que votre annonce s'affiche, informez le SDK Google Mobile Ads des événements d'impression et de clic, ainsi que des autres événements d'annonce qui se produisent pendant le cycle de vie de la présentation de votre annonce.

Remarque : Le SDK Google Mobile Ads suit séparément les événements d'impression, mais il est également important que vous transmettiez l'événement d'impression de votre réseau publicitaire afin que nous puissions vérifier s'il existe des écarts.

Implémenter l'adaptateur d'enchères

Pour créer un adaptateur d'enchères pour le SDK Google Mobile Ads, vous devez étendre la classe abstraite RtbAdapter. Les sections suivantes expliquent chaque méthode abstraite dans RtbAdapter.

getSDKVersionInfo()

Vous devez indiquer ici la version de votre SDK. Cette version est transmise à votre enchérisseur dans la requête OpenRTB.

Cette méthode vous oblige à renvoyer un VersionInfo. L'exemple ci-dessous montre comment convertir la version de chaîne de votre SDK en VersionInfo..

@Override
public VersionInfo getSDKVersionInfo() {
  // Get your SDK's version as a string. E.g. "1.2.3"
  // String versionString = YourSdk.getVersion();
  String splits[] = versionString.split("\\.");
  if (splits.length >= 3) {
      int major = Integer.parseInt(splits[0]);
      int minor = Integer.parseInt(splits[1]);
      int micro = Integer.parseInt(splits[2]);
      return new VersionInfo(major, minor, micro);
   }

   String logMessage = String.format("Unexpected SDK version format: %s." +
           "Returning 0.0.0 for SDK version.", sdkVersion);
   Log.w(TAG, logMessage);
   return new VersionInfo(0, 0, 0);
}

getVersionInfo()

Vous devez indiquer ici la version de votre adaptateur. Cette version est transmise à votre enchérisseur dans la requête OpenRTB.

Les adaptateurs Open Source et versionnés de Google utilisent un système de numérotation à quatre chiffres, mais VersionInfo n'en autorise que trois. Pour contourner ce problème, il est recommandé de combiner les deux derniers chiffres dans la version du correctif, comme indiqué ci-dessous.

@Override
public VersionInfo getVersionInfo() {
  // Get your adapters's version as a string. E.g. "1.2.3.0"
  String versionString = BuildConfig.VERSION_NAME;
  String splits[] = versionString.split("\\.");
  if (splits.length >= 4) {
      int major = Integer.parseInt(splits[0]);
      int minor = Integer.parseInt(splits[1]);
      int micro = Integer.parseInt(splits[2]) * 100 + Integer.parseInt(splits[3]);
      return new VersionInfo(major, minor, micro);
    }

    String logMessage = String.format("Unexpected adapter version format: %s." +
                "Returning 0.0.0 for adapter version.", versionString);
    Log.w(TAG, logMessage);
    return new VersionInfo(0, 0, 0);
}

initialize()

Délai avant expiration : 30 secondes

La méthode initialize() est la première méthode appelée dans votre adaptateur. Elle n'est appelée qu'une seule fois par session. Cette méthode vous fournit une liste d'objets MediationConfiguration qui représentent la liste complète des emplacements de cette application configurés pour votre réseau publicitaire. Vous pouvez parcourir cette liste en boucle pour analyser les identifiants de chaque emplacement et transmettre les données pertinentes à votre SDK pour l'initialisation.

Une fois votre SDK initialisé et prêt à recevoir des demandes d'annonces, appelez la méthode onInitializationSucceeded() de InitializationCompleteCallback. Ce rappel est transmis aux éditeurs d'applications afin qu'ils sachent qu'ils peuvent commencer à charger des annonces.

Remarque : La méthode initialize() est appelée sur une instance jetable d'un adaptateur. Aucune autre méthode ne sera appelée sur cette instance spécifique. Si votre adaptateur doit enregistrer l'état à la suite de cette méthode, tout état doit être statique.

@Override
public void initialize(Context context,
    InitializationCompleteCallback initializationCompleteCallback,
    List<MediationConfiguration> mediationConfigurations) {
  // Initialize your ad network's SDK.
  ...

  // Invoke the InitializationCompleteCallback once initialization completes.
  initializationCompleteCallback.onInitializationSucceeded();
}

collectSignals()

Délai avant expiration : 1 seconde

Chaque fois que l'éditeur demande une annonce, une nouvelle instance de votre RtbAdapter est créée et la méthode collectSignals() est appelée. Cette instance de RtbAdapter sera utilisée pendant toute la durée du cycle de vie de la demande d'annonce, de la réponse et du rendu pour cette annonce. La méthode collectSignals() permet à votre adaptateur de fournir des signaux provenant de l'appareil à envoyer à votre enchérisseur dans une requête OpenRTB.

collectSignals() est appelé sur un thread d'arrière-plan. Le SDK Google Mobile Ads demande simultanément des signaux à tous les adaptateurs participant aux enchères. Veuillez être respectueux et limiter les appels au thread UI pendant cette période. Toute tâche lourde que votre adaptateur ou SDK doit effectuer pour collecter des signaux doit être effectuée dans la méthode initialize() et mise en cache.

Une fois vos signaux prêts, appelez le rappel onSuccess() avec vos signaux encodés.

Voici un exemple d'implémentation :

@Override
public void collectSignals(RtbSignalData rtbSignalData,
                           SignalCallbacks signalCallbacks) {
  String signals = YourSdk.getSignals();
  signalCallbacks.onSuccess(signals);
}

Si votre adaptateur ne parvient pas à collecter les signaux, appelez signalCallbacks.onFailure() avec une chaîne expliquant l'erreur qui s'est produite.

Remarque : La chaîne de signaux peut représenter n'importe quel objet et peut être dans n'importe quel format, tel que JSON brut, encodé en Base64 ou toute autre forme de chiffrement de votre choix. Il est recommandé de chiffrer les signaux pour s'assurer qu'ils sont opaques en dehors de votre réseau.

Implémenter des méthodes de chargement d'annonces

Délai avant expiration : 10 secondes

Si votre enchérisseur renvoie l'enchère gagnante, le SDK Google Mobile Ads appelle votre adaptateur pour charger l'annonce gagnante, en vous transmettant toutes les données renvoyées par votre enchérisseur dont votre SDK a besoin pour charger cette annonce.

La méthode de chargement exacte appelée dépend du format d'annonce pour lequel cette demande est effectuée :

Format d'annonce	Méthode de chargement
Bannière	loadBannerAd()
Interstitiel	loadInterstitialAd()
Avec récompense	loadRewardedAd()

Implémentez ces méthodes pour les formats d'annonces compatibles avec votre adaptateur.

La méthode de chargement est appelée sur le thread d'UI, sur la même instance de l'adaptateur à partir duquel vous avez fourni des signaux. Cette méthode vous fournit les paramètres suivants :

• Un MediationAdConfiguration, qui contient les paramètres dont votre SDK a besoin pour charger l'annonce de l'enchère gagnante, comme la réponse à l'enchère et les identifiants que l'éditeur a configurés dans l'UI AdMob.

• Objet MediationAdLoadCallback utilisé pour informer le SDK Google Mobile Ads lorsque le chargement réussit ou échoue.

Une fois que votre SDK a chargé l'annonce, appelez mediationAdLoadCallback.onSuccess(). Si le chargement de l'annonce événementielle échoue, appelez mediationAdLoadCallback.onFailure() avec une chaîne expliquant l'erreur qui s'est produite.

La méthode mediationAdLoadCallback.onSuccess() exige que vous transmettiez un objet conforme à l'une des interfaces "Ad" définies par le SDK Google Mobile Ads. Ces interfaces publicitaires vous demandent de fournir des informations sur l'annonce.

MediationAdConfiguration dispose également d'une méthode getWatermark() permettant de renvoyer une chaîne encodée en base64 représentant une image PNG. Cette image doit être affichée en mosaïque dans une superposition transparente sur vos annonces. Contactez Google pour obtenir des conseils supplémentaires sur la façon d'afficher le filigrane. Il contient des métadonnées sur l'annonce diffusée, que les éditeurs peuvent utiliser pour déterminer la source des annonces diffusées.

Pour les bannières, vous devrez fournir la vue de la bannière. Pour les annonces interstitielles et avec récompense, vous serez invité à implémenter une méthode show() pour afficher l'annonce ultérieurement. Nous vous recommandons de faire en sorte que la classe qui charge l'annonce soit également responsable de l'implémentation de ces méthodes d'annonce.

Voici un exemple d'implémentation de loadBannerAd(). N'oubliez pas que l'implémentation de votre adaptateur sera différente, car votre adaptateur s'intègre à un autre SDK.

public final class SampleRtbAdapter extends RtbAdapter {
  ...

  @Override
  public void loadBannerAd(
      MediationBannerAdConfiguration adConfiguration,
      MediationAdLoadCallback<MediationBannerAd, MediationBannerAdCallback> callback) {

      SampleBannerRenderer bannerRenderer =
          new SampleBannerRenderer(adConfiguration, callback);
      bannerRenderer.render();
    }
}

// Renders a banner ad, and forwards callbacks to Google Mobile Ads SDK.
public class SampleBannerRenderer implements MediationBannerAd {
  private MediationBannerAdConfiguration adConfiguration;
  private final MediationAdLoadCallback<MediationBannerAd, MediationBannerAdCallback> adLoadCallback;
  private AdView adView;
  private MediationBannerAdCallback callback;

  public SampleRtbBannerRenderer(
      MediationBannerAdConfiguration adConfiguration,
      MediationAdLoadCallback<MediationBannerAd, MediationBannerAdCallback> adLoadCallback) {
    this.adConfiguration = adConfiguration;
    this.adLoadCallback = adLoadCallback;
  }

  public void render() {
    adView = new AdView(adConfiguration.getContext());
    adView.setAdSize(adConfiguration.getAdSize());
    // serverParameters are the parameters entered in the AdMob UI for your network.
    adView.setAdUnitId(adConfiguration.getServerParameters().getString("adUnitId"));

    // Map the callbacks from your SDK to Google's SDK.
    adView.setAdListener(new AdListener() {
      // See the next step for more information on callback mapping.
      // ...
    });

    // Get the bid response and watermark from the ad configuration and
    // pass the relevant information to your SDK.
    String ad = adConfiguration.getBidResponse();
    String watermark = adConfiguration.getWatermark();
    Bundle extras = new Bundle();
    extras.putString("bid", ad);
    extras.putString("watermark", watermark);
    AdRequest request = new AdRequest.Builder()
        .addNetworkExtrasBundle(AdMobAdapter.class, extras)
        .build();
    adView.loadAd(request);
  }

  // MediationBannerAd implementation

  @NonNull
  @Override
  public View getView() {
    return adView;
  }
}

Relayer les événements de cycle de vie de la présentation des annonces

L'adaptateur est responsable en dernier ressort de la notification au SDK Google Mobile Ads de tous les événements de cycle de vie de la présentation, afin qu'ils puissent être transmis à l'éditeur. L'éditeur s'attend à ce que ces rappels soient effectués à des moments précis, quel que soit le réseau publicitaire qui diffuse l'annonce. Il est donc important que le plus grand nombre possible de ces rappels soient invoqués, et au bon moment, afin que le SDK Google Mobile Ads puisse les transmettre à l'éditeur.

Les adaptateurs doivent appeler les événements suivants, le cas échéant :

Communes à tous les formats
Méthode	Quand appeler
reportAdClicked()	L'utilisateur a cliqué sur l'annonce.
reportAdImpression()	L'annonce a généré une impression.
onAdOpened()	L'annonce s'affichait en plein écran.
onAdClosed()	La vue plein écran de l'annonce a été fermée.
onAdLeftApplication()	L'annonce a incité l'utilisateur à quitter l'application.
Annonces avec récompense
onRewarded()	L'utilisateur reçoit une récompense.
Rappels vidéo (annonces avec récompense et natives)
onVideoStarted()	La vidéo de l'annonce a commencé.
onVideoCompleted()	La vidéo de l'annonce a été visionnée en intégralité.

L'adaptateur récupère un objet MediationAdLoadCallback<MediationAdT, MediationAdCallbackT> lors de l'appel de mediationAdLoadCallback.onSuccess(). Les adaptateurs sont censés conserver cet objet et l'utiliser pour appeler les événements de présentation qui se produisent sur votre annonce.

En général, la plupart de ces événements sont déclenchés par le SDK de votre réseau publicitaire. Le rôle de l'adaptateur est simplement de mapper les rappels du SDK de votre réseau publicitaire sur le SDK Google Mobile Ads.

L'exemple suivant montre comment transférer les rappels de l'écouteur d'annonces de votre SDK vers le SDK Google Mobile Ads :

adView.setAdListener(new AdListener() {
    public void onAdLoaded() {
        callback = adLoadCallback.onSuccess(SampleBannerRenderer.this);
    }

    public void onAdImpression() {
        if (callback != null) {
            callback.reportAdImpression();
        }
    }

    public void onAdFailedToLoad(LoadAdError adError) {
        adLoadCallback.onFailure("Error: " + adError.toString());
    }

    public void onAdClosed() {
        if (callback != null) {
            callback.onAdClosed();
        }
    }

    public void onAdOpened() {
        if (callback != null) {
            callback.onAdOpened();
            callback.reportAdClicked();
        }
    }

    public void onAdLeftApplication() {
        if (callback != null) {
            callback.onAdLeftApplication();
        }
    }
});

Composants requis pour le suivi des impressions d'annonces natives

Le SDK Google Mobile Ads enregistre une impression pour une annonce native lorsqu'un pixel de l'annonce est visible. Si le SDK de votre réseau publicitaire exige l'affichage de composants spécifiques pour générer une impression valide, votre enchérisseur peut indiquer ces composants natifs requis dans la réponse à l'enchère. Le SDK Google Mobile Ads valide ensuite que vos composants natifs requis sont affichés avant d'enregistrer une impression.

Pour en savoir plus sur la façon de spécifier des composants obligatoires supplémentaires dans la réponse aux enchères, consultez la documentation sur les composants natifs obligatoires.

Point clé : Toutes les impressions rendues non valides en raison des composants natifs supplémentaires requis par votre réseau publicitaire auront une incidence sur votre ratio d'événements facturables pour cet éditeur.

Afficher les erreurs d'annonce

Pour les formats plein écran, tels que les interstitiels et les annonces avec récompense, vous fournirez une implémentation de MediationInterstitialAd ou MediationRewardedAd dans le rappel de chargement réussi, afin que le SDK Google Mobile Ads puisse demander à votre adaptateur d'afficher l'annonce.

Le SDK Google Mobile Ads s'attend à ce que, si un adaptateur a réussi à charger une annonce, celle-ci soit prête à être diffusée lorsque l'éditeur le demande. Cela signifie que chaque appel d'affichage doit générer une impression.

Toutefois, il peut arriver que vous ne puissiez pas diffuser d'annonce. Si vous ne pouvez pas afficher l'annonce, appelez le rappel onAdFailedToShow() pour annuler l'impression.

Le tableau ci-dessous montre comment les rappels de présentation affectent l'enregistrement des impressions pour les formats d'annonces plein écran :

Rappel	Résultat
onAdOpened()	Impression recorded
onAdFailedToShow()	Impression failure^1
Aucune des réponses ci-dessus pendant plusieurs secondes	Impression recorded

¹ Pour les impressions ayant échoué, votre réseau publicitaire n'est pas facturé pour l'impression, mais cela a un impact sur l'ajustement de votre taux d'événements facturables. Pour en savoir plus, consultez Signaux de demande d'enchères.

L'exemple de simulation suivant illustre un cycle de vie de chargement/d'affichage dans lequel un appel d'affichage d'annonce peut échouer.

final class SampleRtbAdapter extends RtbAdapter implements MediationRewardedAd {

 private MediationRewardedAdCallback callback;
 private RewardedAd rewardedAd;

 ...

  @Override
  public void loadRewardedAd(
      MediationRewardedAdConfiguration adConfiguration,
      final MediationAdLoadCallback<MediationRewardedAd, MediationRewardedAdCallback> loadCallback) {

    // Load an ad. This mock example uses Google's SDK, but in practice
    // your adapter will load the ad using your ad network's SDK.
    RewardedAd.load(adConfiguration.getContext(),
        "ca-app-pub-3940256099942544/5224354917",
        new AdRequest.Builder().build(),
        new RewardedAdLoadCallback() {
          @Override
          public void onAdLoaded(@NonNull RewardedAd rewardedAd) {
            // When the ad loads, invoke the load success callback.
            callback = loadCallback.onSuccess(SampleRtbAdapter.this);
          }
        });
  }

  @Override
  public void showAd(Context context) {
    // In this mock example, your ad network requires an activity context, but
    // didn't receive one, making you unable to show the ad.
    if (!(context instanceof Activity)) {
      AdError error = new AdError(1, "Context must be an activity",
          "com.google.ads.mediation.sample");
      callback.onAdFailedToShow(error);
    }

    // This example shows Google SDK's callbacks, but it's likely your SDK
    // has similar presentation callbacks.
    rewardedAd.setFullScreenContentCallback(new FullScreenContentCallback() {
      @Override
      public void onAdShowedFullScreenContent() {
        // Your ad network SDK successfully showed the ad. Call onAdOpened().
        callback.onAdOpened();
      }

      @Override
      public void onAdFailedToShowFullScreenContent(AdError adError) {
        // Your ad network SDK failed to show the ad, invoke onAdFailedToShow.
        // In practice, you will map your SDK's error to an AdError.
        AdError error = new AdError(adError.getCode(), adError.getMessage(),
            adError.getDomain());
        callback.onAdFailedToShow(adError);
      }
    });


    rewardedAd.show((Activity) context, ...);
  }
}