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:. En outre, créez une 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émenter le protocole
GADMediationNativeAdRecevoir et signaler les rappels d'événements d'annonce au SDK Google Mobile Ads
Le paramètre facultatif défini dans l'interface utilisateur AdMob 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 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 correctement ou rencontre une erreur, vous
appelle 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 que votre adaptateur implémente. Pour cet exemple, le SDK d'exemple possède 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);
}
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.
Nous allons maintenant examiner de plus près les détails de l'implémentation de 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 de médiation peuvent fournir des composants supplémentaires en plus 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 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. Les informations sur les composants Image (qu'il s'agisse d'objets UIImage réels ou simplement de valeurs NSURL) doivent être renvoyées au SDK Google Mobile Ads à l'aide de cette classe.
Voici comment la classe de mappeur gère la création d'un GADNativeAdImage pour 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'impression et de clic
Le SDK Google Mobile Ads et le SDK de médiation doivent savoir quand une impression ou un clic se produit, mais un seul SDK doit suivre ces événements. Les événements personnalisés peuvent utiliser deux approches différentes, selon que le SDK de médiation permet ou non de suivre les impressions et les clics par lui-même.
Suivre les clics et les 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. Le protocole GADMediationNativeAd 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 médiatisée :
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 pour la médiation
Certains SDK avec médiation peuvent préférer suivre les clics et les impressions eux-mêmes. Dans ce cas, vous devez implémenter les méthodes handlesUserClicks et handlesUserImpressions, comme indiqué dans l'extrait de code ci-dessous. En renvoyant YES, vous indiquez que l'événement personnalisé est responsable du suivi de ces événements et qu'il en informera le SDK Google Mobile Ads lorsqu'ils se produiront.
Les événements personnalisés qui remplacent le suivi des clics et des impressions peuvent utiliser le message didRenderInView: pour transmettre la vue de l'annonce native à l'objet d'annonce native du SDK médiatisé afin de permettre au SDK médiatisé d'effectuer le suivi réel. L'exemple de SDK de notre projet d'exemple d'événement personnalisé (à partir duquel les extraits de code de ce guide ont été extraits) n'utilise pas cette approche. Toutefois, si c'était le cas, le code de l'événement personnalisé appellerait la méthode setNativeAdView:view:, comme indiqué dans l'extrait de code 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];
}
Transmettre les événements de médiation au 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 transférer les événements de présentation du SDK tiers 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 de rappels :
Cette opération termine l'implémentation des événements personnalisés pour les annonces natives. Exemple complet est disponible sur GitHub