Pré-requisitos
Conclua a configuração de eventos personalizados.
Solicitar um anúncio nativo
Quando o item de linha do evento personalizado é alcançado na cadeia de mediação em cascata,
o método loadNativeAd:adConfiguration:completionHandler: é chamado no
nome da classe que você forneceu ao criar um evento
personalizado. Nesse caso,
esse método está em SampleCustomEvent, que chama
o método loadNativeAd:adConfiguration:completionHandler: na
SampleCustomEventNative
Para solicitar um anúncio nativo, crie ou modifique uma classe que implemente
GADMediationAdapter e loadNativeAd:adConfiguration:completionHandler:. Se
uma classe que estende GADMediationAdapter já existir, implemente
loadNativeAd:adConfiguration:completionHandler: nela. Além disso, crie um
nova classe para implementar GADMediationNativeAd.
Em nosso exemplo de evento personalizado,
SampleCustomEvent implementa
na interface GADMediationAdapter e delega para
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` é responsável pelas seguintes tarefas:
Como carregar o anúncio nativo
Implementação do protocolo
GADMediationNativeAd.Receber e relatar callbacks de eventos de anúncio para o SDK dos anúncios para dispositivos móveis do Google.
O parâmetro opcional definido na interface da AdMob é
incluído na configuração do anúncio.
O parâmetro pode ser acessado usando
adConfiguration.credentials.settings[@"parameter"]. Esse parâmetro é
normalmente é um identificador de bloco de anúncios que um SDK de rede de publicidade exige ao
instanciando um objeto de anúncio.
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 o anúncio for buscado ou encontrar um erro,
você vai chamar GADMediationNativeAdLoadCompletionHandler. Em caso de sucesso,
transmita a classe que implementa GADMediationNativeAd com um valor de nil;
para o parâmetro error; em caso de falha, transmita o erro que você
encontrados.
Normalmente, esses métodos são implementados dentro de callbacks do
SDK de terceiros implementado pelo adaptador. Para este exemplo, o SDK de exemplo
tem uma SampleNativeAdDelegate com callbacks 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);
}
Mapear anúncios nativos
Diferentes SDKs têm formatos exclusivos para anúncios nativos. Uma pessoa pode retornar objetos que contêm um "title" campo, por exemplo, enquanto outro pode ter "manchete". Além disso, os métodos usados para rastrear impressões e processar os cliques podem variar de um SDK para outro.
Para resolver esses problemas, quando um evento personalizado recebe um objeto de anúncio nativo do
SDK mediado, ele precisa usar uma classe que implementa GADMediationNativeAd,
como SampleCustomEventNativeAd, para "mapear" o objeto de anúncio nativo do SDK mediado
para que ele corresponda à interface esperada pelo SDK dos anúncios para dispositivos móveis do Google.
Agora vamos analisar os detalhes de implementação do
SampleCustomEventNativeAd.
Armazene seus mapeamentos
Espera-se que GADMediationNativeAd implemente determinadas propriedades que são
mapeadas de outras propriedades do 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;
}
Algumas redes mediadas podem fornecer recursos adicionais além dos definidos pelo
SDK dos anúncios para dispositivos móveis do Google. O protocolo GADMediationNativeAd inclui um método
chamado extraAssets, que o SDK dos anúncios para dispositivos móveis do Google usa para recuperar qualquer um
essas opções "extras" recursos de seu mapeador.
Mapear recursos de imagem
O mapeamento de recursos de imagem é mais complicado do que o mapeamento de tipos de dados
mais simples, como NSString ou double. As imagens podem ser transferidas por download automaticamente ou
retornadas como valores de URL. A densidade de pixels também pode variar.
Para ajudar a gerenciar esses detalhes, o SDK dos anúncios para dispositivos móveis do Google oferece a
classe GADNativeAdImage. Informações de recursos de imagem (seja do UIImage real)
objetos ou apenas valores NSURL) devem ser retornados ao SDK dos anúncios para dispositivos móveis do Google
usando essa classe.
Veja como a classe de mapeador gerencia a criação de um GADNativeAdImage para conter o
imagem do ícone:
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 impressão e clique
Tanto o SDK dos anúncios para dispositivos móveis do Google quanto o SDK mediado precisam saber quando uma impressão ou um clique ocorre, mas apenas um SDK precisa acompanhar esses eventos. Há duas abordagens diferentes que os eventos personalizados podem usar, dependendo se o SDK mediado oferece suporte ao rastreamento de impressões e cliques por conta própria.
Acompanhar cliques e impressões com o SDK dos anúncios para dispositivos móveis do Google
Se o SDK mediado não executar o próprio acompanhamento de impressões e cliques, mas
oferecer métodos para registrar cliques e impressões, o SDK dos anúncios para dispositivos móveis do Google poderá
acompanhar esses eventos e notificar o adaptador. O protocolo GADMediationNativeAd
inclui dois métodos: didRecordImpression: e
didRecordClickOnAssetWithName:view:viewController: que eventos personalizados podem
implementar para chamar o método correspondente no objeto de anúncio 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];
}
}
Como a classe que implementa o GADMediationNativeAd
tiver uma referência ao objeto de anúncio nativo do SDK de amostra, poderá chamar o método
método mais apropriado nesse objeto para relatar um clique ou uma impressão. O método
didRecordClickOnAssetWithName:view:viewController: usa um único
parâmetro: o objeto View correspondente ao recurso de anúncio nativo que recebeu
o clique.
Rastrear cliques e impressões com o SDK mediado
Alguns SDKs mediados podem preferir rastrear cliques e impressões por conta própria. Nesse
caso, implemente os métodos handlesUserClicks e
handlesUserImpressions, conforme mostrado no snippet abaixo. Ao retornar
YES, você indica que o evento personalizado é responsável pelo rastreamento
esses eventos e notificará o SDK dos anúncios para dispositivos móveis do Google quando eles ocorrerem.
Eventos personalizados que substituem o rastreamento de cliques e impressões podem usar o método
Mensagem didRenderInView: para transmitir a visualização do anúncio nativo ao SDK mediado.
objeto de anúncio nativo para permitir que o SDK mediado faça o rastreamento real. A amostra
SDK do nosso projeto de exemplo de evento personalizado (do qual os snippets de código deste guia
foram tomadas) não adota essa abordagem" mas, em caso afirmativo, o código do evento
chamaria o método setNativeAdView:view:, conforme mostrado no snippet abaixo:
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];
}
Encaminhar eventos de mediação ao SDK dos anúncios para dispositivos móveis do Google
Depois de chamar
GADMediationNativeLoadCompletionHandler
com um anúncio carregado, o delegado GADMediationNativeAdEventDelegate retornado
pode ser usado pelo adaptador para encaminhar eventos de apresentação do
ao SDK dos anúncios para dispositivos móveis do Google.
É importante que seu evento personalizado encaminhe o maior número possível de callbacks para que o app receba esses eventos equivalentes do SDK dos anúncios para dispositivos móveis do Google. Veja um exemplo de como usar callbacks:
Isso conclui a implementação de eventos personalizados para anúncios nativos. O exemplo completo está disponível no GitHub.