Prerequisiti
Completa la configurazione degli eventi personalizzati.
Richiedere un annuncio nativo
Quando l'elemento pubblicitario dell'evento personalizzato viene raggiunto nella catena di mediazione a cascata,
il metodo loadNativeAd:adConfiguration:completionHandler:
viene chiamato
il nome della classe che hai fornito durante la creazione di un'immagine
dell'evento. In questo caso,
questo metodo è in SampleCustomEvent
, che quindi chiama
il metodo loadNativeAd:adConfiguration:completionHandler:
in
SampleCustomEventNative
.
Per richiedere un annuncio nativo, crea o modifica una classe che implementa
GADMediationAdapter
e loadNativeAd:adConfiguration:completionHandler:
. Se
esiste già una classe che estende GADMediationAdapter
, implementa
loadNativeAd:adConfiguration:completionHandler:
lì. Inoltre, crea un'istanza
nuova classe per implementare GADMediationNativeAd
.
Nel nostro esempio di evento personalizzato,
SampleCustomEvent
implementa
all'interfaccia GADMediationAdapter
e poi delega
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" è responsabile delle seguenti attività:
Caricamento dell'annuncio nativo
Implementazione del protocollo
GADMediationNativeAd
.Ricezione e generazione di report dai callback di eventi di annuncio all'SDK Google Mobile Ads
Il parametro facoltativo definito nell'interfaccia utente di Ad Manager è
incluse nella configurazione dell'annuncio.
È possibile accedere al parametro tramite
adConfiguration.credentials.settings[@"parameter"]
. Questo parametro è
di solito un identificatore di unità pubblicitaria richiesto dall'SDK della rete pubblicitaria quando
creare un'istanza di un oggetto annuncio.
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]; }
Se l'annuncio viene recuperato correttamente o se riscontra un errore,
chiama GADMediationNativeAdLoadCompletionHandler
. In caso di successo,
passa attraverso la classe che implementa GADMediationNativeAd
con un valore nil
per il parametro di errore; in caso di errore, passa l'errore
riscontrati.
In genere, questi metodi sono implementati all'interno dei callback
SDK di terze parti implementato
dall'adattatore. Per questo esempio, l'SDK di esempio
ha un SampleNativeAdDelegate
con callback pertinenti:
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); }
Mappare gli annunci nativi
Ogni SDK ha i propri formati univoci per gli annunci nativi. Uno dei risultati potrebbe essere restituito che contengono un "titolo" campo, ad esempio, mentre un altro potrebbe "headline". Inoltre, i metodi utilizzati per tenere traccia delle impressioni i clic possono variare da un SDK all'altro.
Per risolvere questi problemi, quando un evento personalizzato riceve un oggetto annuncio nativo dalla
per l'SDK con mediazione, deve utilizzare una classe che implementa GADMediationNativeAd
,
come SampleCustomEventNativeAd
, per "mappare" l'oggetto annuncio nativo
dell'SDK con mediazione
in modo che corrisponda all'interfaccia prevista dall'SDK Google Mobile Ads.
Ora diamo un'occhiata più da vicino ai dettagli di implementazione
SampleCustomEventNativeAd
.
Archivia le tue mappature
GADMediationNativeAd
dovrebbe implementare determinate proprietà che
mappate dalle proprietà dell'altro 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; }
Alcune reti mediate possono fornire asset aggiuntivi oltre a quelli definiti
SDK Google Mobile Ads. Il protocollo GADMediationNativeAd
include un metodo
denominato extraAssets
, utilizzato dall'SDK Google Mobile Ads per recuperare uno degli
questi "extra" gli asset del mappatore.
Asset immagine mappa
La mappatura degli asset immagine è più complessa rispetto alla mappatura di dati più semplici
di tipo NSString
o double
. Le immagini possono essere scaricate automaticamente
restituiti come valori URL. Anche la densità dei pixel può variare.
Per aiutarti a gestire questi dettagli, l'SDK Google Mobile Ads fornisce le
GADNativeAdImage
corso. Informazioni sugli asset immagine (se si tratta di UIImage
effettivi
o solo valori NSURL
) devono essere restituiti all'SDK Google Mobile Ads
utilizzando questa classe.
Ecco come gestisce la classe Mapper creando un GADNativeAdImage
per contenere il
immagine icona:
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] ]; }
Eventi di impressioni e clic
Sia l'SDK Google Mobile Ads sia l'SDK con mediazione devono sapere quando si verifica un'impressione o un clic, ma solo un SDK deve monitorare questi eventi. Là sono due approcci diversi che gli eventi personalizzati possono utilizzare, a seconda che l'evento l'SDK con mediazione supporta il monitoraggio delle impressioni e dei clic autonomamente.
Monitora clic e impressioni con l'SDK Google Mobile Ads
Se l'SDK con mediazione non esegue il proprio monitoraggio delle impressioni e dei clic,
fornisce metodi per registrare clic e impressioni, l'SDK Google Mobile Ads può
monitorare questi eventi e inviare una notifica all'adattatore. Protocollo GADMediationNativeAd
include due metodi: didRecordImpression:
e
didRecordClickOnAssetWithName:view:viewController:
che gli eventi personalizzati possono
implementare per chiamare il metodo corrispondente sull'oggetto annuncio nativo mediato:
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]; } }
Poiché la classe che implementa l'GADMediationNativeAd
contiene un riferimento all'oggetto annuncio nativo dell'SDK di esempio, può chiamare il metodo
metodo appropriato su quell'oggetto per segnalare un clic o un'impressione. Tieni presente che
Il metodo didRecordClickOnAssetWithName:view:viewController:
richiede una singola
parametro: l'oggetto View
corrispondente all'asset annuncio nativo che ha ricevuto
al clic.
Monitora clic e impressioni con l'SDK con mediazione
Alcuni SDK mediati potrebbero preferire il monitoraggio dei clic e delle impressioni in autonomia. Nella
in questo caso, devi implementare handlesUserClicks
e
handlesUserImpressions
metodi come mostrato nello snippet di seguito. Di ritorno
YES
, indichi che l'evento personalizzato si assume la responsabilità del monitoraggio
questi eventi e informerà l'SDK Google Mobile Ads quando si verificano.
Gli eventi personalizzati che sostituiscono il monitoraggio dei clic e delle impressioni possono utilizzare
didRenderInView:
messaggio per trasmettere la visualizzazione dell'annuncio nativo all'SDK con mediazione
per consentire all'SDK con mediazione di eseguire il monitoraggio effettivo. L'esempio
SDK del nostro progetto di esempio di evento personalizzato (da cui gli snippet di codice di questa guida)
già adottati) non utilizza questo approccio" Se lo fosse, il codice evento personalizzato
chiama il metodo setNativeAdView:view:
come mostrato nello snippet seguente:
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]; }
Inoltrare gli eventi di mediazione all'SDK Google Mobile Ads
Dopo aver chiamato
GADMediationNativeLoadCompletionHandler
con un annuncio caricato, il delegato GADMediationNativeAdEventDelegate
restituito
può quindi essere utilizzato dall'adattatore per inoltrare gli eventi di presentazione
di terze parti all'SDK Google Mobile Ads.
È importante che l'evento personalizzato inoltri il maggior numero di questi callback possibile, in modo che la tua app riceva questi eventi equivalenti dall'account Google l'SDK Mobile Ads. Ecco un esempio di utilizzo delle richiamate:
L'implementazione degli eventi personalizzati per gli annunci nativi è completata. L'esempio completo è disponibile su GitHub.