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:adConfiguration:completionHandler:
est appelée au niveau
que vous avez fourni lors de la création d'un objet
l'événement. Dans ce cas, cette méthode se trouve dans SampleCustomEvent
, qui appelle ensuite la méthode loadNativeAd:adConfiguration:completionHandler:
dans SampleCustomEventNative
.
Pour demander une annonce native, créez ou modifiez une classe qui implémente
GADMediationAdapter
et loadNativeAd:adConfiguration:completionHandler:
. Si une classe qui étend GADMediationAdapter
existe déjà, implémentez loadNativeAd:adConfiguration:completionHandler:
. De plus, créez un
Nouvelle classe pour implémenter GADMediationNativeAd
.
Dans notre exemple d'événement personnalisé,
Implémentation de SampleCustomEvent
l'interface GADMediationAdapter
, puis délègue à
SampleCustomEventNative
Swift
import GoogleMobileAds class SampleCustomEvent: NSObject, GADMediationAdapter { fileprivate var nativeAd: SampleCustomEventNativeAd? func loadNativeAd( for adConfiguration: GADMediationNativeAdConfiguration, completionHandler: @escaping GADMediationNativeAdLoadCompletionHandler ) { self.nativeAd = SampleCustomEventNativeAd() self.nativeAd?.loadNativeAd( for: adConfiguration, completionHandler: completionHandler) } }
Objective-C
#import "SampleCustomEvent.h" @implementation SampleCustomEvent SampleCustomEventNativeAd *sampleNativeAd; - (void)loadNativeAdForAdConfiguration: (GADMediationNativeAdConfiguration *)adConfiguration completionHandler: (GADMediationNativeAdLoadCompletionHandler) completionHandler { sampleNative = [[SampleCustomEventNativeAd alloc] init]; [sampleNative loadNativeAdForAdConfiguration:adConfiguration completionHandler:completionHandler]; }
SampleCustomEventNative est responsable des tâches suivantes:
Charger l'annonce native
Implémentation du protocole
GADMediationNativeAd
.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.credentials.settings[@"parameter"]
Ce paramètre est
généralement un identifiant de bloc d'annonces requis par un SDK de réseau publicitaire
d'instancier un objet d'annonce.
Swift
class SampleCustomEventNativeAd: NSObject, GADMediationNativeAd { /// The Sample Ad Network native ad. var nativeAd: SampleNativeAd? /// The ad event delegate to forward ad rendering events to the Google Mobile /// Ads SDK. var delegate: GADMediationNativeAdEventDelegate? /// Completion handler called after ad load var completionHandler: GADMediationNativeLoadCompletionHandler? func loadNativeAd( for adConfiguration: GADMediationNativeAdConfiguration, completionHandler: @escaping GADMediationNativeLoadCompletionHandler ) { let adLoader = SampleNativeAdLoader() let sampleRequest = SampleNativeAdRequest() // The Google Mobile Ads SDK requires the image assets to be downloaded // automatically unless the publisher specifies otherwise by using the // GADNativeAdImageAdLoaderOptions object's disableImageLoading property. If // your network doesn't have an option like this and instead only ever // returns URLs for images (rather than the images themselves), your adapter // should download image assets on behalf of the publisher. This should be // done after receiving the native ad object from your network's SDK, and // before calling the connector's adapter:didReceiveMediatedNativeAd: method. sampleRequest.shouldDownloadImages = true sampleRequest.preferredImageOrientation = NativeAdImageOrientation.any sampleRequest.shouldRequestMultipleImages = false let options = adConfiguration.options for loaderOptions: GADAdLoaderOptions in options { if let imageOptions = loaderOptions as? GADNativeAdImageAdLoaderOptions { sampleRequest.shouldRequestMultipleImages = imageOptions.shouldRequestMultipleImages // If the GADNativeAdImageAdLoaderOptions' disableImageLoading property is // YES, the adapter should send just the URLs for the images. sampleRequest.shouldDownloadImages = !imageOptions.disableImageLoading } else if let mediaOptions = loaderOptions as? GADNativeAdMediaAdLoaderOptions { switch mediaOptions.mediaAspectRatio { case GADMediaAspectRatio.landscape: sampleRequest.preferredImageOrientation = NativeAdImageOrientation.landscape case GADMediaAspectRatio.portrait: sampleRequest.preferredImageOrientation = NativeAdImageOrientation.portrait default: sampleRequest.preferredImageOrientation = NativeAdImageOrientation.any } } } // This custom event uses the server parameter to carry an ad unit ID, which // is the most common use case. adLoader.delegate = self adLoader.adUnitID = adConfiguration.credentials.settings["parameter"] as? String self.completionHandler = completionHandler adLoader.fetchAd(sampleRequest) } }
Objective-C
#import "SampleCustomEventNativeAd.h" @interface SampleCustomEventNativeAd () <SampleNativeAdDelegate, GADMediationNativeAd> { /// The sample native ad. SampleNativeAd *_nativeAd; /// The completion handler to call when the ad loading succeeds or fails. GADMediationNativeLoadCompletionHandler _loadCompletionHandler; /// The ad event delegate to forward ad rendering events to the Google Mobile /// Ads SDK. id<GADMediationNativeAdEventDelegate> _adEventDelegate; } @end - (void)loadNativeAdForAdConfiguration: (GADMediationNativeAdConfiguration *)adConfiguration completionHandler:(GADMediationNativeLoadCompletionHandler) completionHandler { __block atomic_flag completionHandlerCalled = ATOMIC_FLAG_INIT; __block GADMediationNativeLoadCompletionHandler originalCompletionHandler = [completionHandler copy]; _loadCompletionHandler = ^id<GADMediationNativeAdEventDelegate>( _Nullable id<GADMediationNativeAd> ad, NSError *_Nullable error) { // Only allow completion handler to be called once. if (atomic_flag_test_and_set(&completionHandlerCalled)) { return nil; } id<GADMediationNativeAdEventDelegate> delegate = nil; if (originalCompletionHandler) { // Call original handler and hold on to its return value. delegate = originalCompletionHandler(ad, error); } // Release reference to handler. Objects retained by the handler will also // be released. originalCompletionHandler = nil; return delegate; }; SampleNativeAdLoader *adLoader = [[SampleNativeAdLoader alloc] init]; SampleNativeAdRequest *sampleRequest = [[SampleNativeAdRequest alloc] init]; // The Google Mobile Ads SDK requires the image assets to be downloaded // automatically unless the publisher specifies otherwise by using the // GADNativeAdImageAdLoaderOptions object's disableImageLoading property. If // your network doesn't have an option like this and instead only ever returns // URLs for images (rather than the images themselves), your adapter should // download image assets on behalf of the publisher. This should be done after // receiving the native ad object from your network's SDK, and before calling // the connector's adapter:didReceiveMediatedNativeAd: method. sampleRequest.shouldDownloadImages = YES; sampleRequest.preferredImageOrientation = NativeAdImageOrientationAny; sampleRequest.shouldRequestMultipleImages = NO; sampleRequest.testMode = adConfiguration.isTestRequest; for (GADAdLoaderOptions *loaderOptions in adConfiguration.options) { if ([loaderOptions isKindOfClass:[GADNativeAdImageAdLoaderOptions class]]) { GADNativeAdImageAdLoaderOptions *imageOptions = (GADNativeAdImageAdLoaderOptions *)loaderOptions; sampleRequest.shouldRequestMultipleImages = imageOptions.shouldRequestMultipleImages; // If the GADNativeAdImageAdLoaderOptions' disableImageLoading property is // YES, the adapter should send just the URLs for the images. sampleRequest.shouldDownloadImages = !imageOptions.disableImageLoading; } else if ([loaderOptions isKindOfClass:[GADNativeAdMediaAdLoaderOptions class]]) { GADNativeAdMediaAdLoaderOptions *mediaOptions = (GADNativeAdMediaAdLoaderOptions *)loaderOptions; switch (mediaOptions.mediaAspectRatio) { case GADMediaAspectRatioLandscape: sampleRequest.preferredImageOrientation = NativeAdImageOrientationLandscape; break; case GADMediaAspectRatioPortrait: sampleRequest.preferredImageOrientation = NativeAdImageOrientationPortrait; break; default: sampleRequest.preferredImageOrientation = NativeAdImageOrientationAny; break; } } else if ([loaderOptions isKindOfClass:[GADNativeAdViewAdOptions class]]) { _nativeAdViewAdOptions = (GADNativeAdViewAdOptions *)loaderOptions; } } // This custom event uses the server parameter to carry an ad unit ID, which // is the most common use case. NSString *adUnit = adConfiguration.credentials.settings[@"parameter"]; adLoader.adUnitID = adUnit; adLoader.delegate = self; [adLoader fetchAd:sampleRequest]; }
Que l'annonce soit récupérée correctement ou rencontre une erreur, vous
appelle GADMediationNativeAdLoadCompletionHandler
. En cas de succès,
transmettre la classe qui implémente GADMediationNativeAd
avec une valeur nil
.
pour le paramètre d'erreur. en cas d'échec, transmettez l'erreur
rencontrés.
En règle générale, ces méthodes sont implémentées dans les rappels du SDK tiers que votre adaptateur implémente. Dans cet exemple, l'exemple de SDK
comporte un SampleNativeAdDelegate
avec les rappels appropriés:
Swift
func adLoader( _ adLoader: SampleNativeAdLoader, didReceive nativeAd: SampleNativeAd ) { extraAssets = [ SampleCustomEventConstantsSwift.awesomenessKey: nativeAd.degreeOfAwesomeness ?? "" ] if let image = nativeAd.image { images = [GADNativeAdImage(image: image)] } else { let imageUrl = URL(fileURLWithPath: nativeAd.imageURL) images = [GADNativeAdImage(url: imageUrl, scale: nativeAd.imageScale)] } if let mappedIcon = nativeAd.icon { icon = GADNativeAdImage(image: mappedIcon) } else { let iconURL = URL(fileURLWithPath: nativeAd.iconURL) icon = GADNativeAdImage(url: iconURL, scale: nativeAd.iconScale) } adChoicesView = SampleAdInfoView() self.nativeAd = nativeAd if let handler = completionHandler { delegate = handler(self, nil) } } func adLoader( _ adLoader: SampleNativeAdLoader, didFailToLoadAdWith errorCode: SampleErrorCode ) { let error = SampleCustomEventUtilsSwift.SampleCustomEventErrorWithCodeAndDescription( code: SampleCustomEventErrorCodeSwift .SampleCustomEventErrorAdLoadFailureCallback, description: "Sample SDK returned an ad load failure callback with error code: \(errorCode)" ) if let handler = completionHandler { delegate = handler(nil, error) } }
Objective-C
- (void)adLoader:(SampleNativeAdLoader *)adLoader didReceiveNativeAd:(SampleNativeAd *)nativeAd { if (nativeAd.image) { _images = @[ [[GADNativeAdImage alloc] initWithImage:nativeAd.image] ]; } else { NSURL *imageURL = [[NSURL alloc] initFileURLWithPath:nativeAd.imageURL]; _images = @[ [[GADNativeAdImage alloc] initWithURL:imageURL scale:nativeAd.imageScale] ]; } if (nativeAd.icon) { _icon = [[GADNativeAdImage alloc] initWithImage:nativeAd.icon]; } else { NSURL *iconURL = [[NSURL alloc] initFileURLWithPath:nativeAd.iconURL]; _icon = [[GADNativeAdImage alloc] initWithURL:iconURL scale:nativeAd.iconScale]; } // The sample SDK provides an AdChoices view (SampleAdInfoView). If your SDK // provides image and click through URLs for its AdChoices icon instead of an // actual UIView, the adapter is responsible for downloading the icon image // and creating the AdChoices icon view. _adChoicesView = [[SampleAdInfoView alloc] init]; _nativeAd = nativeAd; _adEventDelegate = _loadCompletionHandler(self, nil); } - (void)adLoader:(SampleNativeAdLoader *)adLoader didFailToLoadAdWithErrorCode:(SampleErrorCode)errorCode { NSError *error = SampleCustomEventErrorWithCodeAndDescription( SampleCustomEventErrorAdLoadFailureCallback, [NSString stringWithFormat:@"Sample SDK returned an ad load failure " @"callback with error code: %@", errorCode]); _adEventDelegate = _loadCompletionHandler(nil, error); }
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.
Pour résoudre ces problèmes, lorsqu'un événement personnalisé reçoit un objet d'annonce native de
son SDK par médiation, il doit utiliser une classe qui implémente GADMediationNativeAd
,
comme SampleCustomEventNativeAd
, par "map" l'objet d'annonce native du SDK
afin qu'elle corresponde à l'interface attendue par le SDK Google Mobile Ads.
Examinons maintenant de plus près les détails de l'implémentation
SampleCustomEventNativeAd
Stocker vos mappages
GADMediationNativeAd
doit implémenter certaines propriétés
mappées à partir des propriétés d'autres SDK:
Swift
var nativeAd: SampleNativeAd? var headline: String? { return nativeAd?.headline } var images: [GADNativeAdImage]? var body: String? { return nativeAd?.body } var icon: GADNativeAdImage? var callToAction: String? { return nativeAd?.callToAction } var starRating: NSDecimalNumber? { return nativeAd?.starRating } var store: String? { return nativeAd?.store } var price: String? { return nativeAd?.price } var advertiser: String? { return nativeAd?.advertiser } var extraAssets: [String: Any]? { return [ SampleCustomEventConstantsSwift.awesomenessKey: nativeAd?.degreeOfAwesomeness ?? "" ] } var adChoicesView: UIView? var mediaView: UIView? { return nativeAd?.mediaView }
Objective-C
/// Used to store the ad's images. In order to implement the /// GADMediationNativeAd protocol, we use this class to return the images /// property. NSArray<GADNativeAdImage *> *_images; /// Used to store the ad's icon. In order to implement the GADMediationNativeAd /// protocol, we use this class to return the icon property. GADNativeAdImage *_icon; /// Used to store the ad's ad choices view. In order to implement the /// GADMediationNativeAd protocol, we use this class to return the adChoicesView /// property. UIView *_adChoicesView; - (nullable NSString *)headline { return _nativeAd.headline; } - (nullable NSArray<GADNativeAdImage *> *)images { return _images; } - (nullable NSString *)body { return _nativeAd.body; } - (nullable GADNativeAdImage *)icon { return _icon; } - (nullable NSString *)callToAction { return _nativeAd.callToAction; } - (nullable NSDecimalNumber *)starRating { return _nativeAd.starRating; } - (nullable NSString *)store { return _nativeAd.store; } - (nullable NSString *)price { return _nativeAd.price; } - (nullable NSString *)advertiser { return _nativeAd.advertiser; } - (nullable NSDictionary<NSString *, id> *)extraAssets { return @{SampleCustomEventExtraKeyAwesomeness : _nativeAd.degreeOfAwesomeness}; } - (nullable UIView *)adChoicesView { return _adChoicesView; } - (nullable UIView *)mediaView { return _nativeAd.mediaView; } - (BOOL)hasVideoContent { return self.mediaView != nil; }
Certains réseaux avec médiation peuvent fournir des éléments supplémentaires en plus de ceux définis par
SDK Google Mobile Ads. Le protocole GADMediationNativeAd
inclut une méthode
appelée extraAssets
, que le SDK Google Mobile Ads utilise pour récupérer
ces options « supplémentaires » les ressources de votre cartographe.
Composants Image de la carte
Mapper des éléments d'image est plus compliqué que de cartographier des données simples.
types comme NSString
ou double
. Les images peuvent être téléchargées automatiquement ou
renvoyées sous forme de valeurs d'URL. Leur densité de pixels peut également varier.
Pour vous aider à gérer ces informations, le SDK Google Mobile Ads fournit
GADNativeAdImage
. Informations sur le composant Image (s'il s'agit de UIImage
ou seulement les valeurs NSURL
) doivent être renvoyés au SDK Google Mobile Ads.
à l'aide de cette classe.
Voici comment la classe mapper gère la création d'un GADNativeAdImage
pour contenir le
image de l'icône:
Swift
if let image = nativeAd.image { images = [GADNativeAdImage(image: image)] } else { let imageUrl = URL(fileURLWithPath: nativeAd.imageURL) images = [GADNativeAdImage(url: imageUrl, scale: nativeAd.imageScale)] }
Objective-C
if (nativeAd.image) { _images = @[ [[GADNativeAdImage alloc] initWithImage:nativeAd.image] ]; } else { NSURL *imageURL = [[NSURL alloc] initFileURLWithPath:nativeAd.imageURL]; _images = @[ [[GADNativeAdImage alloc] initWithURL:imageURL scale:nativeAd.imageScale] ]; }
É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 que les événements personnalisés peuvent utiliser, selon que 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. Protocole GADMediationNativeAd
comprend deux méthodes: didRecordImpression:
et
didRecordClickOnAssetWithName:view:viewController:
que les événements personnalisés peuvent
pour appeler la méthode correspondante sur l'objet d'annonce native par médiation:
Swift
func didRecordImpression() { nativeAd?.recordImpression() } func didRecordClickOnAsset( withName assetName: GADUnifiedNativeAssetIdentifier, view: UIView, wController: UIViewController ) { nativeAd?.handleClick(on: view) }
Objective-C
- (void)didRecordImpression { if (self.nativeAd) { [self.nativeAd recordImpression]; } } - (void)didRecordClickOnAssetWithName:(GADUnifiedNativeAssetIdentifier)assetName view:(UIView *)view viewController:(UIViewController *)viewController { if (self.nativeAd) { [self.nativeAd handleClickOnView:view]; } }
Comme la classe qui implémente GADMediationNativeAd
contient une référence à l'objet d'annonce native de l'exemple de SDK, il peut appeler la méthode
la méthode appropriée sur cet objet pour enregistrer un clic ou une impression. Notez que
La méthode didRecordClickOnAssetWithName:view:viewController:
n'accepte qu'un seul
: l'objet View
correspondant au composant d'annonce native qui a 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 suivre les clics et les impressions eux-mêmes. Dans
Dans ce cas, vous devez implémenter handlesUserClicks
et
handlesUserImpressions
comme indiqué dans l'extrait ci-dessous. En retour
YES
, vous indiquez que l'événement personnalisé est responsable du suivi
et en informera le SDK Google Mobile Ads.
Les événements personnalisés qui ignorent le suivi des clics et des impressions peuvent utiliser
Message didRenderInView:
pour transmettre la vue de l'annonce native aux SDK associés à la médiation
pour permettre au SDK associé à la médiation d'effectuer le suivi. L'exemple
SDK de notre exemple d'événement personnalisé de projet (à partir duquel les extraits de code de ce guide
ont été prises) n'utilise pas cette approche. Si c'est le cas, le code de l'événement personnalisé
appelle la méthode setNativeAdView:view:
, comme indiqué dans l'extrait ci-dessous:
Swift
func handlesUserClicks() -> Bool { return true } func handlesUserImpressions() -> Bool { return true } func didRender( in view: UIView, clickableAssetViews: [GADNativeAssetIdentifier: UIView], nonclickableAssetViews: [GADNativeAssetIdentifier: UIView], viewController: UIViewController ) { // This method is called when the native ad view is rendered. Here you would pass the UIView // back to the mediated network's SDK. self.nativeAd?.setNativeAdView(view) }
Objective-C
- (BOOL)handlesUserClicks { return YES; } - (BOOL)handlesUserImpressions { return YES; } - (void)didRenderInView:(UIView *)view clickableAssetViews:(NSDictionary<GADNativeAssetIdentifier, UIView *> *) clickableAssetViews nonclickableAssetViews:(NSDictionary<GADNativeAssetIdentifier, UIView *> *) nonclickableAssetViews viewController:(UIViewController *)viewController { // This method is called when the native ad view is rendered. Here you would // pass the UIView back to the mediated network's SDK. Playing video using // SampleNativeAd's playVideo method [_nativeAd setNativeAdView:view]; }
Transférer les événements de médiation au SDK Google Mobile Ads
Une fois que vous avez appelé
GADMediationNativeLoadCompletionHandler
avec une annonce chargée, le délégué GADMediationNativeAdEventDelegate
renvoyé
peut ensuite être utilisé par l'adaptateur pour transférer les événements de présentation à partir du
vers le SDK Google Mobile Ads.
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