Développement de l'adaptateur d'enchères

Ce guide est destiné aux réseaux publicitaires qui cherchent à créer un adaptateur d'enchères afin de 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 éditeur.

L'adaptateur d'enchères est la partie client de l'intégration. Cet 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 doit gérer l'initialisation, la collecte de signaux, le chargement des annonces et la transmission des événements de cycle de vie des annonces. Dans ce guide, nous vous expliquerons comment mettre en œuvre votre adaptateur pour gérer ces opérations.

Remarque :La participation aux enchères nécessite également un enchérisseur capable de répondre aux demandes OpenRTB. Les instructions sur la mise en place d'un enchérisseur n'entrent pas dans le cadre de ce guide.

Workflow d'un adaptateur d'enchères

Initialisation

Vous trouverez ci-dessous un flux détaillé du cycle de vie complet du rendu requête/réponse 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 des signaux à partir du SDK de votre réseau publicitaire à envoyer à votre enchérisseur afin qu'il participe à une demande RTB, puis transférez-les au SDK Google Mobile Ads.

• Étapes 18 à 21: Si votre enchérisseur renvoie l'enchère gagnante, chargez l'annonce en fonction de la réponse de l'enchérisseur. Une fois le chargement terminé, indiquez au SDK Google Mobile Ads que l'annonce a été chargée.

• Étape 23 et ultérieures: pendant la diffusion de votre annonce, informez le SDK Google Mobile Ads des événements d'impression et de clic, ainsi que de tout autre événement d'annonce qui se produit 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 transfériez l'événement d'impression de votre réseau publicitaire afin que nous puissions vérifier les é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 décrivent chaque méthode abstraite dans RtbAdapter.

getSDKVersionInfo()

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

Cette méthode nécessite que vous renvoyiez un VersionInfo. L'exemple ci-dessous montre comment convertir la version de la 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 renvoyer à ce niveau la version de votre adaptateur. Cette version est transmise à l'enchérisseur dans la requête OpenRTB.

Les adaptateurs Open Source avec versions gérées de Google utilisent un schéma de version d'adaptateur à quatre chiffres, mais VersionInfo n'accepte que trois chiffres. 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. Cet appel n'est effectué qu'une seule fois par session. Cette méthode 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 pour analyser les identifiants de chaque emplacement et transmettre les données pertinentes à votre SDK pour l'initialisation.

Une fois que votre SDK est 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 puissent commencer à charger des annonces.

Remarque :La méthode initialize() est appelée sur une instance non prioritaire d'un adaptateur. Aucune autre méthode ne sera appelée sur cette instance particulière. Si votre adaptateur doit enregistrer un é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 instance de votre RtbAdapter est créée et la méthode collectSignals() est appelée. Cette instance de RtbAdapter sera utilisée pendant la durée de la demande d'annonce, de la réponse et du cycle de vie d'affichage de cette annonce. La méthode collectSignals() permet à votre adaptateur de fournir des signaux 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 faire preuve de respect et limiter les appels au thread UI pendant cette période. Tout travail important que votre adaptateur ou SDK doit effectuer pour collecter les signaux doit être effectué dans la méthode initialize() et mis en cache.

Une fois que vos signaux sont 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 de 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. Il peut s'agir de n'importe quel format, par exemple JSON brut, encodé en base64 ou toute autre forme de chiffrement de votre choix. Nous vous recommandons de chiffrer les signaux pour vous assurer qu'ils sont opaques en dehors de votre réseau.

Implémenter des méthodes de chargement des 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 l'enchérisseur et qui doivent être chargées par le SDK.

La méthode de chargement exacte appelée dépend du format d'annonce auquel cette requête est destinée:

Format d'annonce	Méthode de chargement
Bannière	loadBannerAd()
Interstitiel	loadInterstitialAd()
Accordé	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 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 élément MediationAdConfiguration, qui contient les paramètres dont votre SDK a besoin pour charger l'annonce correspondant à l'enchère gagnante, tels que la réponse à l'enchère et tous les identifiants configurés par l'éditeur dans l'interface utilisateur AdMob

• Un objet MediationAdLoadCallback permettant d'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 échoue, appelez mediationAdLoadCallback.onFailure() avec une chaîne expliquant l'erreur qui s'est produite.

La méthode mediationAdLoadCallback.onSuccess() nécessite la transmission d'un objet qui confirme 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() pour renvoyer une chaîne encodée en base64 représentant une image PNG. Cette image doit être superposée à vos annonces de façon transparente. Contactez Google pour obtenir des conseils supplémentaires sur l'affichage du filigrane. Il contient des métadonnées sur l'annonce diffusée afin que les éditeurs puissent déterminer la source des annonces diffusées.

Pour les bannières, vous êtes invité à fournir l'affichage de la bannière. Pour les annonces interstitielles et avec récompense, vous serez invité à implémenter une méthode show() afin de diffuser l'annonce ultérieurement. Nous vous recommandons de faire en sorte que la classe qui charge les annonces 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 the 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;
  }
}

Événements du cycle de vie de la présentation des annonces Relay

La dernière responsabilité de l'adaptateur consiste à informer le SDK Google Mobile Ads de tous les événements du cycle de vie de la présentation, afin qu'ils puissent être transmis à l'éditeur. L'éditeur attend ces rappels à des moments précis, quel que soit le réseau publicitaire qui diffuse l'annonce. Il est donc important d'invoquer autant de rappels que possible et au bon moment, afin que le SDK Google Mobile Ads puisse les transférer à l'éditeur.

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

Commun à 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()	L'affichage en plein écran de l'annonce a été fermé.
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 est terminée.

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

En général, la plupart de ces événements sont générés par le SDK de votre réseau publicitaire. Le rôle de l'adaptateur consiste simplement à mapper les rappels du SDK de votre réseau publicitaire au 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();
        }
    }
});

Assets requis pour le suivi des impressions d'annonces natives

Le SDK Google Mobile Ads enregistre une impression pour une annonce native lorsque 1 px de l'annonce est visible. Si votre SDK de réseau publicitaire nécessite l'affichage d'éléments spécifiques pour générer une impression valide, votre enchérisseur peut indiquer ces éléments natifs obligatoires dans la réponse à l'enchère. Le SDK Google Mobile Ads vérifie ensuite que les éléments natifs requis s'affichent avant l'enregistrement d'une impression.

Consultez la documentation sur les composants natifs requis pour savoir comment spécifier des éléments supplémentaires requis dans la réponse à l'enchère.

Important :Toute impression rendue non valide en raison des composants natifs supplémentaires requis de votre réseau publicitaire aura une incidence sur le ratio d'événements facturables pour cet éditeur.

Afficher les erreurs liées aux annonces

Pour les formats plein écran, comme les annonces interstitielles et avec récompense, dans le rappel de chargement réussi, vous devez fournir une implémentation de MediationInterstitialAd, MediationRewardedAd afin que le SDK Google Mobile Ads puisse demander à votre adaptateur de diffuser l'annonce.

Si un adaptateur a correctement chargé une annonce, le SDK Google Mobile Ads s'attend à ce que celle-ci soit prête à être diffusée lorsque l'éditeur demande à le faire. Cela signifie que chaque appel d'émission doit générer une impression.

Toutefois, il peut arriver que vous ne parveniez pas à diffuser une annonce. Si vous ne pouvez pas diffuser 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

¹ En cas d'échec d'une impression, votre réseau publicitaire n'est pas facturé pour l'impression, mais cela a une incidence sur l'ajustement du tarif des événements facturables. Pour en savoir plus, consultez Signaux de demande d'enchère.

L'exemple suivant illustre un cycle de chargement/émission où un appel d'émission peut entraîner un échec.

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, ...);
  }
}