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:adConfiguration:completionHandler: 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:adConfiguration:completionHandler: method 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: à cet endroit. En outre, créez une classe pour implémenter GADMediationNativeAd.
Dans notre exemple d'événement personnalisé, SampleCustomEvent implémentethe GADMediationAdapter interface , 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:
Chargement de l'annonce native
Implémenter
GADMediationNativeAdprotocolRecevoir 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 Ad Manager est inclus dans la configuration de l'annonce.
Ce 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 lors de l'instanciation d'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 ou qu'elle rencontre une erreur, vous devez appeler GADMediationNativeAdLoadCompletionHandler. En cas de réussite, transmettez la classe qui implémente GADMediationNativeAd avec une valeur nil pour le paramètre d'erreur. En cas d'échec, transmettez l'erreur que vous avez rencontrée.
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 SampleNativeAdDelegate avec des rappels pertinents:
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);
}
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.
Pour résoudre ces problèmes, lorsqu'un événement personnalisé reçoit un objet d'annonce native de son SDK pour la médiation, il doit utiliser une classe qui implémente GADMediationNativeAd, comme SampleCustomEventNativeAd, pour "mapper" l'objet d'annonce native du SDK pour la médiation de sorte qu'il corresponde à l'interface attendue par le SDK Google Mobile Ads.
Examinons maintenant de plus près les détails de l'implémentation pour SampleCustomEventNativeAd.
Stocker vos mises en correspondance
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 utilisés pour la médiation peuvent fournir des éléments supplémentaires au-delà de ceux définis par le 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 éléments "supplémentaires" de votre mappeur.
Composants Image de carte
Mettre en correspondance des éléments image est plus compliqué que de mapper des types de données plus simples tels que NSString ou double. Les images peuvent être téléchargées automatiquement ou renvoyées sous forme d'URL. Leur densité en pixels peut également varier.
Pour vous aider à gérer ces détails, le SDK Google Mobile Ads fournit la classe GADNativeAdImage. Les informations sur le composant Image (qu'il s'agisse d'objets UIImage réels ou uniquement de valeurs NSURL) doivent être renvoyées au SDK Google Mobile Ads à l'aide de cette classe.
Voici comment la classe mapper gère la création d'un GADNativeAdImage destiné à contenir l'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'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.GADMediationNativeAd protocol inclut deux méthodes :didRecordImpression: et didRecordClickOnAssetWithName:view:viewController: 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:
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];
}
}
Étant donné que la classe qui implémente le protocole GADMediationNativeAd protocolcontient une référence à l'objet d'annonce native du SDK Sample, elle peut appeler la méthode appropriée sur cet objet pour signaler un clic ou une impression. Notez que la méthodedidRecordClickOnAssetWithName:view:viewController: 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 implémenter les méthodes handlesUserClicks et handlesUserImpressions, comme indiqué dans l'extrait ci-dessous. En renvoyant YES, vous indiquez que l'événement personnalisé est responsable du suivi de ces événements et vous informez le SDK Google Mobile Ads lorsqu'ils se produisent.
Les événements personnalisés qui ignorent le suivi des clics et des impressions peuvent utiliser le message didRenderInView: pour transmettre l'affichage de l'annonce native à l'objet d'annonce native du SDK pour la médiation, afin de permettre au SDK défini pour la médiation d'effectuer 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. Toutefois, si tel était le cas, le code de l'événement personnalisé appellerait 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 vers le SDK Google Mobile Ads
Une fois que vous avez appelé GADMediationNativeLoadCompletionHandler avec une annonce chargée, l'objet délégué GADMediationNativeAdEventDelegate renvoyé peut être utilisé par l'adaptateur pour transmettre les événements de présentation du SDK tiers au SDK Google Mobile Ads.
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.