Développement d'adaptateurs de médiation pour réseau publicitaire

Ce guide est destiné aux réseaux publicitaires qui souhaitent créer un adaptateur de médiation. Si vous êtes un éditeur, consultez les instructions de médiation pour les éditeurs.

Un adaptateur de médiation constitue la couche de communication entre votre réseau publicitaire et la médiation Google Mobile Ads. Les adaptateurs diffusent des annonces à partir de votre réseau publicitaire tout en transférant les événements publicitaires pertinents à AdMob. Un adaptateur est chargé de mettre en œuvre le protocole GADMAdNetworkAdapter afin de s'assurer qu'il fournit les fonctionnalités requises.

Prérequis

  • Xcode 15.3 ou version ultérieure
  • Cible de déploiement 8.0 ou version ultérieure
  • En-têtes supplémentaires du dossier "Adaptateurs de médiation" du téléchargement du SDK Google Mobile Ads pour iOS

Votre réseau publicitaire doit entretenir une relation de travail établie avec Google pour créer un adaptateur de médiation.

Exemple de réseau publicitaire

Ce guide explique comment créer un adaptateur pour le réseau publicitaire de l'exemple. L'exemple de SDK de réseau publicitaire contient des classes représentatives de celles proposées par la plupart des réseaux publicitaires:

@interface SampleBanner : UILabel

@property(nonatomic, copy) NSString *adUnit;
@property(nonatomic, weak) id<SampleBannerAdDelegate> delegate;
- (void)fetchAd:(SampleAdRequest *)request;

@end

typedef NS_ENUM(NSInteger, SampleErrorCode) {
  SampleErrorCodeBadRequest = 0,
  SampleErrorCodeUnknown = 1,
  SampleErrorCodeNetworkError = 2,
  SampleErrorCodeNoInventory = 3,
};

@interface SampleAdRequest : NSObject

@property(nonatomic, assign) BOOL testMode;
@property(nonatomic, copy) NSArray *keywords;

@end

@interface SampleInterstitial : NSObject

@property(nonatomic, copy) NSString *adUnit;
@property(nonatomic, weak) id<SampleInterstitialAdDelegate> delegate;
@property(nonatomic, assign, getter=isInterstitialLoaded) BOOL interstitialLoaded;
- (void)fetchAd:(SampleAdRequest *)request;
- (void)show;

@end

@protocol SampleBannerAdDelegate
- (void)bannerDidLoad:(SampleBanner *)banner;
- (void)banner:(SampleBanner *)banner didFailToLoadAdWithError:(SampleErrorCode)error;
- (void)bannerWillLeaveApplication:(SampleBanner *)banner;

@end

@protocol SampleInterstitialAdDelegate<NSObject>
- (void)interstitialDidLoad:(SampleInterstitial *)interstitial;
- (void)interstitial:(SampleInterstitial *)interstitial
    didFailToLoadAdWithError:(SampleErrorCode)error;
- (void)interstitialWillPresentScreen:(SampleInterstitial *)interstitial;
- (void)interstitialWillDismissScreen:(SampleInterstitial *)interstitial;
- (void)interstitialDidDismissScreen:(SampleInterstitial *)interstitial;
- (void)interstitialWillLeaveApplication:(SampleInterstitial *)interstitial;

@end

Pour en savoir plus sur ces classes, consultez l'exemple complet d'implémentation du SDK.

Connecteur

Les adaptateurs de médiation interagissent avec le SDK Google Mobile Ads à l'aide d'un objet qui implémente le protocole GADMAdNetworkConnector. À partir de là, nous appellerons cet objet le connecteur. Le connecteur fournit les informations nécessaires pour les demandes d'annonces et permet de rappeler la médiation pour les événements d'annonces et les interactions des utilisateurs. Le connecteur est fourni aux adaptateurs de médiation au moment de l'initialisation. Configurez votre adaptateur pour stocker le connecteur dans une variable d'instance:

- (id)initWithGADMAdNetworkConnector:(id<GADMAdNetworkConnector>)c {
  if ((self = [super init])) {
    _connector = c;
  }
  return self;
}

Paramètres du serveur

Votre réseau publicitaire a probablement besoin d'un ou plusieurs identifiants pour identifier un éditeur. Le réseau publicitaire exemple, par exemple, nécessite un bloc d'annonces. Ces paramètres de serveur obligatoires sont fournis à l'adaptateur via la méthode credentials, qui renvoie une NSDictionary d'identifiants et des valeurs correspondantes. La ligne de code suivante récupère le paramètre de serveur nommé ad_unit pour le réseau publicitaire exemple à partir du connecteur:

self.interstitialAd.adUnit = [[self.connector credentials] objectForKey:@"ad_unit"];

Configuration du réseau de médiation

Les réseaux publicitaires doivent informer AdMob des paramètres de serveur requis pour leur réseau. Cela permet à AdMob de configurer votre réseau dans l'interface.

Lorsque vous activez votre réseau pour la médiation dans l'interface, AdMob vous demande de saisir les valeurs nécessaires pour instancier votre adaptateur. La capture d'écran ci-dessous montre qu'un identifiant d'emplacement d'application (APID, Application Placement Identifier, APID) est obligatoire pour Millennial Media et qu'un ID d'application est requis pour InMobi.

Pour en savoir plus sur la configuration des réseaux publicitaires de médiation, consultez cet article.

Envoyer une demande d'annonce via la médiation

Pour les requêtes de bannière de médiation, la méthode getBannerWithSize est appelée immédiatement après l'instanciation de l'adaptateur. Cette méthode ne renvoie rien. Il indique à l'adaptateur qu'il doit lancer une récupération asynchrone des annonces sur le réseau. Faites en sorte que votre adaptateur écoute les rappels de votre SDK. Si votre SDK n'est pas compatible avec la taille d'annonce donnée ou n'accepte pas les bannières, appelez la méthode adapter:didFailAd: au niveau du connecteur.

L'implémentation de getBannerWithSize pour le réseau publicitaire exemple se présente comme suit:

- (void)getBannerWithSize:(GADAdSize)adSize {
  //The adapter should fail immediately if the adSize is not supported
  if (!GADAdSizeEqualToSize(adSize, GADAdSizeBanner) &&
      !GADAdSizeEqualToSize(adSize, GADAdSizeMediumRectangle) &&
      !GADAdSizeEqualToSize(adSize, GADAdSizeFullBanner) &&
      !GADAdSizeEqualToSize(adSize, GADAdSizeLeaderboard)) {
    NSString *errorDesc =
        [NSString stringWithFormat:@"Invalid ad type %@, not going to get ad.",
                                   NSStringFromGADAdSize(adSize)];
    NSDictionary *errorInfo = [NSDictionary
        dictionaryWithObjectsAndKeys:errorDesc, NSLocalizedDescriptionKey, nil];
    NSError *error = [NSError errorWithDomain:GADErrorDomain
                                         code:GADErrorMediationInvalidAdSize
                                     userInfo:errorInfo];
    [self.connector adapter:self didFailAd:error];
    return;
  }
  self.bannerAd = [[SampleBanner alloc]
      initWithFrame:CGRectMake(0, 0, adSize.size.width, adSize.size.height)];

  self.bannerAd.delegate = self;
  self.bannerAd.adUnit = [[self.connector credentials] objectForKey:@"ad_unit"];

  // Setup request parameters.
  SampleAdRequest *request = [[SampleAdRequest alloc] init];
  request.testMode = self.connector.testMode;
  request.keywords = self.connector.userKeywords;
  [self.bannerAd fetchAd:request];
  NSLog(@"Requesting banner from Sample Ad Network");
}

Paramètres de ciblage supplémentaires

Le connecteur contient des informations de ciblage courantes que vous pouvez consulter pour le ciblage des annonces:

  • userKeywords
  • testMode
  • childDirectedTreatment

Options de médiation supplémentaires

Les options de médiation supplémentaires permettent à votre réseau publicitaire d'accepter des entrées ou des paramètres de ciblage supplémentaires qui ne sont pas couverts par les paramètres de demande supplémentaires fournis par le connecteur. Cette fonctionnalité peut être fournie via une classe qui implémente le protocole GADAdNetworkExtras. La classe SampleAdNetworkExtras est présentée ci-dessous à titre d'exemple:

@interface SampleAdNetworkExtras : NSObject <GADAdNetworkExtras>
/// Should ad volume audio be muted.
@property(nonatomic, assign) BOOL muteAudio;

@end

Les éditeurs doivent transmettre une instance de votre sous-classe GADAdNetworkExtras lorsqu'ils effectuent une demande d'annonce. Cette instance de votre sous-classe GADAdNetworkExtras est accessible via le connecteur. Voici comment utiliser les options de médiation supplémentaires lorsque vous créez une demande d'annonce pour votre réseau:

SampleAdRequest *request = [[SampleAdRequest alloc] init];
SampleAdNetworkExtras *myAdNetworkExtras = [self.connector networkExtras];
request.muteAudio = myAdNetworkExtras.muteAudio;
[self.bannerAd fetchAd:request];

Pour vous assurer que votre sous-classe GADAdNetworkExtras est accessible via le connecteur, implémentez networkExtrasClass et renvoyez votre sous-classe GADAdNetworkExtras:

+ (Class<GADAdNetworkExtras>)networkExtrasClass {
  return [SampleAdNetworkExtras class];
}

Si votre adaptateur n'utilise pas d'extras de médiation, la méthode networkExtrasClass renvoie Nil.

Avertir la médiation

Demandez à votre adaptateur d'implémenter l'écouteur d'annonces pour votre réseau et de transférer les rappels d'événements d'annonce pertinents via le connecteur. Le tableau ci-dessous explique quand appeler chaque méthode déléguée:

Méthode Quand appeler
adapter:didReceiveAdView: La demande de bannière a bien été effectuée.
adapter:didFailAd: Échec de la demande de bannière.
adapterDidGetAdClick: L'utilisateur a cliqué sur la bannière.
adapterWillPresentFullScreenModal: La bannière affiche une superposition dans l'application.
adapterWillDismissFullScreenModal: La superposition dans l'application se ferme.
adapterDidDismissFullScreenModal: La superposition dans l'application a été fermée.
adapterWillLeaveApplication: L'application sera placée en arrière-plan ou arrêtée, car l'utilisateur a cliqué sur une annonce qui lancera une autre application.

L'exemple suivant implémente l'interface SampleBannerAdDelegate de l'exemple de réseau publicitaire pour transférer les messages d'erreur et d'état:

- (void)bannerDidLoad:(SampleBanner *)banner {
  [self.connector adapter:self didReceiveAdView:banner];
}

- (void)banner:(SampleBanner *)banner didFailWithError:(SampleErrorCode)error {
  [self.connector adapter:self
                didFailAd:[NSError errorWithDomain:@"Ad request failed"
                                              code:error
                                          userInfo:nil]];
}

- (void)bannerWillLeaveApplication:(SampleBanner *)banner {
  [self.connector adapterDidGetAdClick:self];
  [self.connector adapterWillLeaveApplication:self];
}

Lancer la superposition dans l'application plutôt qu'une application externe

Lorsqu'un utilisateur clique sur une bannière, l'annonce peut ouvrir une superposition plein écran ou une application externe (comme Safari ou la plate-forme de téléchargement d'applications). Les rappels du connecteur à appeler dans ces deux cas sont différents.

Si un clic sur une bannière ouvre une superposition en plein écran, appelez adapterWillPresentFullScreenModal: lors de la présentation de la superposition. Lorsque la superposition est fermée, appelez à la fois adapterWillDismissFullScreenModal: et adapterDidDismissFullScreenModal:.

Si un clic sur une bannière (ou un clic en superposition en plein écran) force l'utilisateur à quitter l'application, appelez le rappel adapterWillLeaveApplication:.

Vous disposez désormais d'un adaptateur de médiation fonctionnel pour les bannières. Pour référence, une implémentation complète de SampleAdapter est disponible sur GitHub.

Implémenter un adaptateur pour les interstitiels

L'implémentation de l'adaptateur pour les annonces interstitielles est semblable à celle des bannières. La méthode getInterstitial est appelée immédiatement après l'instanciation de l'adaptateur. Cette méthode ne renvoie rien. L'adaptateur doit lancer une récupération d'annonce asynchrone sur le réseau. Faites en sorte que votre adaptateur agisse en tant que délégué à votre SDK pour écouter les rappels. Si votre SDK n'est pas compatible avec les annonces interstitielles, appelez la méthode adapter:didFailAd: du connecteur comme suit:

- (void)getInterstitial {
  self.interstitialAd = [[SampleInterstitial alloc] init];
  self.interstitialAd.delegate = self;
  self.interstitialAd.adUnit =
      [[self.connector credentials] objectForKey:@"ad_unit"];

  SampleAdRequest *request = [[SampleAdRequest alloc] init];
  // Setup request parameters.
  request.testMode = self.connector.testMode;
  request.keywords = self.connector.userKeywords;

  [self.interstitialAd fetchAd:request];
  NSLog(@"Requesting interstitial from Sample Ad Network");
}

Tout comme avec MediationBannerAdapter, le connecteur vous permet de recevoir des informations sur l'identification de l'éditeur et le ciblage des annonces.

Avertir la médiation

Demandez à votre adaptateur d'implémenter le délégué d'annonce pour votre réseau et de transférer les rappels d'événements d'annonce pertinents via le connecteur. Le tableau ci-dessous explique quand appeler chaque méthode déléguée:

Méthode Quand appeler
adapterDidReceiveInterstitial: La demande d'interstitiel a bien été envoyée.
adapter:didFailInterstitial: Échec de la demande d'interstitiel.
adapterDidGetAdClick: L'utilisateur a cliqué sur l'interstitiel.
adapterWillPresentInterstitial: L'interstitiel sera alors diffusé.
adapterWillDismissInterstitial: L'interstitiel va être ignoré.
adapterDidDismissInterstitial: L'interstitiel a été ignoré.
adapterWillLeaveApplication: L'application s'exécute en arrière-plan ou s'arrête, car l'utilisateur a cliqué sur une annonce pour lancer une autre application.

L'exemple suivant implémente l'interface SampleInterstitialAdDelegate de la régie publicitaire exemple pour transférer les messages d'erreur et d'état:

- (void)interstitialDidLoad:(SampleInterstitial *)interstitial {
  [self.connector adapterDidReceiveInterstitial:self];
}

- (void)interstitial:(SampleInterstitial *)interstitial
    didFailWithError:(SampleErrorCode)error {
  [self.connector adapter:self
      didFailInterstitial:[NSError errorWithDomain:@"Ad request failed"
                                              code:error
                                          userInfo:nil]];
}

- (void)interstitialWillPresentScreen:(SampleInterstitial *)interstitial {
  [self.connector adapterWillPresentInterstitial:self];
}

- (void)interstitialWillDismissScreen:(SampleInterstitial *)interstitial {
  [self.connector adapterWillDismissInterstitial:self];
}

- (void)interstitialDidDismissScreen:(SampleInterstitial *)interstitial {
  [self.connector adapterDidDismissInterstitial:self];
}

Présenter un interstitiel

Une fois que l'adaptateur a appelé adapterDidReceiveInterstitial, attendez que presentInterstitialFromRootViewController soit appelé avant d'afficher l'interstitiel. Le développeur de l'application décide quand afficher l'interstitiel, c'est-à-dire plusieurs minutes après sa réception.

Voici une implémentation de presentInterstitialFromRootViewController: pour le réseau publicitaire exemple:

- (void)presentInterstitialFromRootViewController:
    (UIViewController *)rootViewController {
  if ([self.interstitialAd isLoaded]) {
    [self.interstitialAd show];
  }
}

Votre adaptateur de médiation est prêt à gérer les annonces interstitielles. Pour référence, une implémentation complète de SampleAdapter est disponible sur GitHub.

Questions fréquentes

Dois-je inclure l'adaptateur dans ma bibliothèque SDK ou dans une bibliothèque distincte ?
Nous vous recommandons d'inclure l'adaptateur dans la bibliothèque de votre SDK afin que les développeurs n'aient à référencer qu'une seule bibliothèque pour intégrer votre réseau.
Que faire si mon adaptateur n'est compatible qu'avec les bannières ?

Si votre adaptateur n'est compatible qu'avec les bannières, demandez-lui de transmettre un événement d'erreur à la médiation pour les demandes d'interstitiels:

- (void)getInterstitial {
  NSDictionary *errorInfo = @{ NSLocalizedDescriptionKey : @"Some error" };
  NSError *error = [NSError errorWithDomain:GADErrorDomain
                                       code:GADErrorInvalidRequest
                                   userInfo:errorInfo];
  [self.connector adapter:self didFailInterstitial:error];
  return;
}
Que faire si mon adaptateur n'est compatible qu'avec les annonces interstitielles ?

Si votre adaptateur n'est compatible qu'avec les interstitiels, demandez-lui de transmettre un événement d'erreur à la médiation pour les demandes de bannières:

- (void)getBannerWithSize:(GADAdSize)adSize {
  NSDictionary *errorInfo = @{ NSLocalizedDescriptionKey : @"Some error" };
  NSError *error =
      [NSError errorWithDomain:GADErrorDomain
                          code:GADErrorInvalidRequest
                      userInfo:errorInfo];
  [self.connector adapter:self didFailAd:error];
  return;
}