Requisitos previos
Completa la configuración de eventos personalizados.
Cómo solicitar un anuncio nativo
Cuando se llega a la línea de pedido del evento personalizado en la cadena de mediación en cascada, se llama al método loadNativeAd:adConfiguration:completionHandler:
en el nombre de la clase que proporcionaste cuando creaste un evento personalizado. En este caso, ese método está en SampleCustomEvent
, que luego llama al método loadNativeAd:adConfiguration:completionHandler:
en SampleCustomEventNative
.
Para solicitar un anuncio nativo, crea o modifica una clase que implemente GADMediationAdapter
y loadNativeAd:adConfiguration:completionHandler:
. Si ya existe una clase que extiende GADMediationAdapter
, implementa loadNativeAd:adConfiguration:completionHandler:
allí. Además, crea una clase nueva para implementar GADMediationNativeAd
.
En nuestro ejemplo de evento personalizado, SampleCustomEvent
implementa la interfaz GADMediationAdapter
y, luego, delega a 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` es responsable de las siguientes tareas:
Cómo cargar el anuncio nativo
Implementa el protocolo
GADMediationNativeAd
.Cómo recibir y generar informes de devoluciones de llamada de eventos de anuncios en el SDK de anuncios de Google para dispositivos móviles
El parámetro opcional definido en la IU de Ad Manager se incluye en la configuración del anuncio.
Se puede acceder al parámetro a través de adConfiguration.credentials.settings[@"parameter"]
. Por lo general, este parámetro es un identificador de unidad de anuncios que requiere un SDK de red publicitaria cuando crea una instancia de un objeto de anuncio.
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]; }
Independientemente de si el anuncio se recupera correctamente o encuentra un error, llamarás a GADMediationNativeAdLoadCompletionHandler
. En caso de éxito, pasa la clase que implementa GADMediationNativeAd
con un valor nil
para el parámetro de error. En caso de error, pasa el error que encontraste.
Por lo general, estos métodos se implementan dentro de devoluciones de llamada del SDK de terceros que implementa tu adaptador. En este ejemplo, el SDK de ejemplo tiene un SampleNativeAdDelegate
con devoluciones de llamada relevantes:
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); }
Anuncios nativos de Maps
Los diferentes SDKs tienen sus propios formatos únicos para los anuncios nativos. Por ejemplo, uno podría mostrar objetos que contienen un campo "título", mientras que otro podría tener "título principal". Además, los métodos que se usan para hacer un seguimiento de las impresiones y procesar los clics pueden variar de un SDK a otro.
Para abordar estos problemas, cuando un evento personalizado recibe un objeto de anuncio nativo de su SDK mediado, debe usar una clase que implemente GADMediationNativeAd
, como SampleCustomEventNativeAd
, para "asignar" el objeto de anuncio nativo del SDK mediado de modo que coincida con la interfaz que espera el SDK de anuncios de Google para dispositivos móviles.
Ahora, analicemos con más detalle los detalles de la implementación de
SampleCustomEventNativeAd
.
Almacena tus asignaciones
Se espera que GADMediationNativeAd
implemente ciertas propiedades que se asignan desde otras propiedades del 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; }
Algunas redes mediadas pueden proporcionar recursos adicionales más allá de los que define el SDK de Google Mobile Ads. El protocolo GADMediationNativeAd
incluye un método llamado extraAssets
que el SDK de anuncios de Google para dispositivos móviles usa para recuperar cualquiera de estos recursos "extra" de tu asignador.
Recursos de imagen del mapa
Asignar recursos de imagen es más complicado que asignar tipos de datos más simples, como NSString
o double
. Es posible que las imágenes se descarguen automáticamente o se muestren como valores de URL. Su densidad de píxeles también puede variar.
Para ayudarte a administrar estos detalles, el SDK de anuncios de Google para dispositivos móviles proporciona la clase GADNativeAdImage
. La información del recurso de imagen (ya sea que se trate de objetos UIImage
reales o solo de valores NSURL
) se debe mostrar al SDK de anuncios de Google para dispositivos móviles con esta clase.
A continuación, se muestra cómo la clase del asignador controla la creación de un GADNativeAdImage
para contener la imagen del ícono:
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] ]; }
Eventos de impresión y clic
Tanto el SDK de anuncios de Google para dispositivos móviles como el SDK mediado deben saber cuándo se produce una impresión o un clic, pero solo un SDK debe hacer un seguimiento de estos eventos. Existen dos enfoques diferentes que pueden usar los eventos personalizados, según si el SDK mediado admite el seguimiento de impresiones y clics por sí solo.
Realiza un seguimiento de los clics y las impresiones con el SDK de anuncios de Google para dispositivos móviles
Si el SDK mediado no realiza su propio seguimiento de clics e impresiones, pero proporciona métodos para registrar clics e impresiones, el SDK de anuncios de Google para dispositivos móviles puede hacer un seguimiento de estos eventos y notificar al adaptador. El protocolo GADMediationNativeAd
incluye dos métodos: didRecordImpression:
y didRecordClickOnAssetWithName:view:viewController:
que los eventos personalizados pueden implementar para llamar al método correspondiente en el objeto de anuncio nativo mediado:
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]; } }
Debido a que la clase que implementa el protocolo GADMediationNativeAd
tiene una referencia al objeto de anuncio nativo del SDK de ejemplo, puede llamar al método apropiado en ese objeto para informar un clic o una impresión. Ten en cuenta que el método didRecordClickOnAssetWithName:view:viewController:
toma un solo parámetro: el objeto View
correspondiente al recurso de anuncio nativo que recibió el clic.
Realiza un seguimiento de los clics y las impresiones con el SDK mediado
Es posible que algunos SDKs mediados prefieran hacer un seguimiento de los clics y las impresiones por su cuenta. En ese caso, debes implementar los métodos handlesUserClicks
y handlesUserImpressions
como se muestra en el siguiente fragmento. Cuando devuelves YES
, indicas que el evento personalizado se responsabiliza de hacer un seguimiento de estos eventos y notificará al SDK de anuncios de Google para dispositivos móviles cuando ocurran.
Los eventos personalizados que anulan el seguimiento de clics e impresiones pueden usar el mensaje didRenderInView:
para pasar la vista del anuncio nativo al objeto de anuncio nativo del SDK mediado para permitir que el SDK mediado realice el seguimiento real. El SDK de muestra de nuestro proyecto de ejemplo de eventos personalizados (del que se tomaron los fragmentos de código de esta guía) no usa este enfoque, pero, si lo hiciera, el código del evento personalizado llamaría al método setNativeAdView:view:
como se muestra en el siguiente fragmento:
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]; }
Reenvía eventos de mediación al SDK de anuncios de Google para dispositivos móviles
Una vez que hayas llamado a GADMediationNativeLoadCompletionHandler
con un anuncio cargado, el adaptador puede usar el objeto delegado GADMediationNativeAdEventDelegate
que se muestra para reenviar eventos de presentación del SDK de terceros al SDK de anuncios de Google para dispositivos móviles.
Es importante que tu evento personalizado reenvíe tantas de estas devoluciones de llamada como sea posible, de modo que tu app reciba estos eventos equivalentes del SDK de Google Mobile Ads. Este es un ejemplo del uso de devoluciones de llamada:
Con esto se completa la implementación de eventos personalizados para los anuncios nativos. El ejemplo completo está disponible en GitHub.