Implementar um adaptador de anúncios premiados

Um adaptador de mediação recebe mensagens e solicitações do SDK dos anúncios para dispositivos móveis do Google e se comunica com um SDK de rede de terceiros para atender a essas solicitações.

Este guia é destinado a redes de publicidade que querem criar um adaptador de mediação de anúncios premiados para a mediação de anúncios para dispositivos móveis do Google. Um SDK de amostra é usado nos snippets de código abaixo para fins de demonstração. Confira uma implementação completa de um adaptador criado para este SDK de amostra no projeto de mediação doiOS (link em inglês). Este guia explica como criar o adaptador.

Definir o nome da classe do adaptador e os parâmetros do servidor

As redes de publicidade mediadas pela plataforma de Mediação da AdMob geralmente exigem um ou mais identificadores para identificar um editor. Eles são representados como parâmetros do servidor e definidos na configuração de uma rede de publicidade de terceiros para mediação na interface da AdMob.

Antes de desenvolver um adaptador de mediação, você precisa fornecer ao Google o nome da classe do adaptador e outros parâmetros necessários para ter acesso à sua rede de anúncios.

Conformidade com o protocolo GADMediationAdapter

A primeira etapa é fazer com que a classe do adaptador implemente o protocolo GADMediationAdapter:

#import <Foundation/Foundation.h>
#import <GoogleMobileAds/GoogleMobileAds.h>
#import <SampleAdSDK/SampleAdSDK.h>

@interface GADMediationAdapterSampleAdNetwork : NSObject <GADMediationAdapter>
@end

Essa mudança garante que sua classe implemente vários métodos discutidos abaixo.

Denunciar classe extra

Se a rede de terceiros quiser permitir que os editores transmitam outros parâmetros opcionais para uma solicitação de anúncio, a classe extras vai precisar ser retornada do método networkExtrasClass. Retorne Nil se o terceiro não oferecer suporte aos extras fornecidos pelo editor.

#import <GoogleMobileAds/GoogleMobileAds.h>

@interface SampleExtras : NSObject<GADAdNetworkExtras>

/// Use this to indicate if debug mode is on for logging.
@property(nonatomic) BOOL debugLogging;

/// Use this to indicate whether to mute audio for video ads.
@property(nonatomic) BOOL muteAudio;

@end

#import "GADMediationAdapterSampleAdNetwork.h"

@implementation GADMediationAdapterSampleAdNetwork
...
+ (Class<GADAdNetworkExtras>)networkExtrasClass {
  return [SampleExtras class];
}
...
@end

Informar números de versão

O adaptador precisa informar ao SDK dos anúncios para dispositivos móveis do Google a versão do adaptador e a do SDK de terceiros. As versões são informadas usando GADVersionNumber.

Os adaptadores de código aberto e com versões do Google usam um esquema de versão de adaptador de quatro dígitos, mas GADVersionNumber permite apenas três dígitos. Para contornar esse problema, é recomendável combinar os dois últimos dígitos na versão do patch, conforme mostrado abaixo:

#import "GADMediationAdapterSampleAdNetwork.h"

@implementation GADMediationAdapterSampleAdNetwork
...
+ (GADVersionNumber)adSDKVersion {
  NSString *versionString = SampleSDKVersion;
  NSArray *versionComponents = [versionString componentsSeparatedByString:@"."];

  GADVersionNumber version = {0};
  if (versionComponents.count >= 3) {
    version.majorVersion = [versionComponents[0] integerValue];
    version.minorVersion = [versionComponents[1] integerValue];
    version.patchVersion = [versionComponents[2] integerValue];
  }
  return version;
}

+ (GADVersionNumber)version {
  NSString *versionString = SampleAdapterVersion;
  NSArray *versionComponents = [versionString componentsSeparatedByString:@"."];

  GADVersionNumber version = {0};
  if (versionComponents.count >= 4) {
    version.majorVersion = [versionComponents[0] integerValue];
    version.minorVersion = [versionComponents[1] integerValue];
    // Adapter versions have 2 patch versions. Multiply the first patch by 100.
    version.patchVersion =
        [versionComponents[2] integerValue] * 100 + [versionComponents[3] integerValue];
  }
  return version;
}
...
@end

Inicializar o adaptador

Quando um app inicializa o SDK dos anúncios para dispositivos móveis do Google, o setUpWithConfiguration:completionHandler: é invocado em todos os adaptadores configurados para o app na IU da AdMob.

O argumento GADMediationServerConfiguration fornece informações sobre todas as posições configuradas para o app na IU da AdMob. Use essas informações para inicializar o SDK da rede de publicidade. Depois que o SDK da rede de publicidade for inicializado, invoque o argumento GADMediationAdapterSetUpCompletionBlock. Esse bloqueio permite informar uma inicialização bem-sucedida ou com falha ao SDK dos anúncios para dispositivos móveis do Google, invocando o gerenciador de conclusão com nil ou um objeto NSError.

#import "SampleAdapter.h"

@implementation SampleAdapter
...
+ (void)setUpWithConfiguration:(GADMediationServerConfiguration *)configuration
             completionHandler:(GADMediationAdapterSetUpCompletionBlock)completionHandler {
  // Since the Sample SDK doesn't need to be initialized, the completion
  //handler is called directly here.
  completionHandler(nil);
}
...
@end

Solicitar um anúncio premiado

Quando um app carrega um anúncio premiado com o SDK dos anúncios para dispositivos móveis do Google, o loadRewardedAdForAdConfiguration:completionHandler: é invocado no adaptador caso sua rede de publicidade seja alcançada na hierarquia de mediação.

Com o GADRewardedLoadCompletionHandler, é possível informar um carregamento de anúncio bem-sucedido ao SDK dos anúncios para dispositivos móveis do Google fornecendo uma referência a um objeto em conformidade com o protocolo GADMediationRewardedAd ou um carregamento de anúncio com falha fornecendo uma referência nil e um objeto NSError. A invocação do gerenciador de conclusão do carregamento retorna um GADMediationRewardedAdEventDelegate que o adaptador precisa manter para o ciclo de vida do anúncio para notificar o SDK dos anúncios para dispositivos móveis do Google sobre qualquer evento subsequente.

#import "SampleAdapter.h"

@interface SampleAdapter () <GADMediationRewardedAd> {
  /// Rewarded ads from Sample SDK.
  SampleRewardedAd *_rewardedAd;

  /// Handles any callback when the sample rewarded ad finishes loading.
  GADMediationRewardedLoadCompletionHandler _loadCompletionHandler;

  /// Delegate for receiving rewarded ad notifications.
  __weak id<GADMediationRewardedAdEventDelegate> _rewardedAdDelegate;
}
@end

@implementation SampleAdapter
...
- (void)loadRewardedAdForAdConfiguration:(GADMediationRewardedAdConfiguration *)adConfiguration
                       completionHandler:
                           (GADMediationRewardedLoadCompletionHandler)completionHandler {
  _loadCompletionHandler = completionHandler;

  NSString *adUnit = adConfiguration.credentials.settings[SampleSDKAdUnitIDKey];
  SampleExtras *extras = adConfiguration.extras;

  _rewardedAd = [[SampleRewardedAd alloc] initWithAdUnitID:adUnit];
  _rewardedAd.enableDebugLogging = extras.enableDebugLogging;

  /// Check the extras to see if the request should be customized.
  SampleAdRequest *request = [[SampleAdRequest alloc] init];
  request.mute = extras.muteAudio;

  /// Set the delegate on the rewarded ad to listen for callbacks from the Sample SDK.
  _rewardedAd.delegate = self;
  [_rewardedAd fetchAd:request];
}
...
@end

Eventos de carregamento de anúncio de redirecionamento

É responsabilidade do adaptador ouvir callbacks do SDK de terceiros e mapeá-los para o callback apropriado do SDK dos anúncios para dispositivos móveis do Google.

Informe o sucesso ou a falha de eventos de carregamento de anúncio de terceiros invocando o loadCompletionHandler com um anúncio ou um erro. Se o gerenciador de conclusão for chamado com um anúncio e nenhum erro, um objeto delegado de evento de anúncio será retornado. Mantenha uma referência a esse delegado para que o adaptador possa redirecionar eventos de apresentação mais tarde.

- (void)rewardedAdDidReceiveAd:(nonnull SampleRewardedAd *)rewardedAd {
  _rewardedAdDelegate = _loadCompletionHandler(self, nil);
}

- (void)rewardedAdDidFailToLoadWithError:(SampleErrorCode)errorCode {
  _loadCompletionHandler(nil, [NSError errorWithDomain:kAdapterErrorDomain
                                                  code:GADErrorNoFill
                                              userInfo:nil]);
}

Veicular o anúncio

Quando o app pede ao SDK dos anúncios para dispositivos móveis do Google para apresentar o anúncio premiado, o SDK chama o método presentFromViewController: na instância de GADMediationRewardedAd fornecida na chamada ao gerenciador de conclusão do carregamento. Aqui, você deve apresentar o anúncio premiado:

- (void)presentFromViewController:(nonnull UIViewController *)viewController {
  if (!_rewardedAd.isReady) {
    NSError *error =
        [NSError errorWithDomain:kAdapterErrorDomain
                            code:0
                        userInfo:@{NSLocalizedDescriptionKey : @"Unable to display ad."}];
    [_rewardedAdDelegate didFailToPresentWithError:error];
    return;
  }
  [_rewardedAd presentFromRootViewController:viewController];
}

Informar eventos de anúncios ao SDK de anúncios para dispositivos móveis

Depois de exibir o anúncio, o adaptador deve informar os eventos de ciclo de vida da apresentação do anúncio usando o mesmo delegado de evento de anúncio retornado no tempo de carregamento do anúncio.

- (void)rewardedAdDidPresent:(nonnull SampleRewardedAd *)rewardedAd {
  [_rewardedAdDelegate willPresentFullScreenView];
  [_rewardedAdDelegate didStartVideo];
  [_rewardedAdDelegate reportImpression];
}

- (void)rewardedAdDidDismiss:(nonnull SampleRewardedAd *)rewardedAd {
  [_rewardedAdDelegate willDismissFullScreenView];
  [_rewardedAdDelegate didEndVideo];
  [_rewardedAdDelegate didDismissFullScreenView];
}
- (void)rewardedAd:(nonnull SampleRewardedAd *)rewardedAd userDidEarnReward:(NSUInteger)reward {
  GADAdReward *aReward =
      [[GADAdReward alloc] initWithRewardType:@"GADMediationAdapterSampleAdNetwork"
                                 rewardAmount:[NSDecimalNumber numberWithUnsignedInt:reward]];
  [_rewardedAdDelegate didRewardUserWithReward:aReward];
}

Os eventos de anúncios que precisam ser informados ao SDK dos anúncios para dispositivos móveis do Google estão detalhados abaixo:

Evento do anúncio	Descrição
willPresentFullScreenView	Notifica o SDK dos anúncios para dispositivos móveis do Google de que o anúncio será exibido.
didStartVideo	Notifica o SDK dos anúncios para dispositivos móveis do Google de que um anúncio premiado começou a ser reproduzido.
reportImpression	Notifica o SDK dos anúncios para dispositivos móveis do Google de que ocorreu uma impressão no anúncio.
didEndVideo	Notifica o SDK dos anúncios para dispositivos móveis do Google de que o anúncio premiado terminou a reprodução.
didRewardUserWithReward	Notifica o SDK dos anúncios para dispositivos móveis do Google de que o usuário ganhou um prêmio.
reportClick	Notifica o SDK dos anúncios para dispositivos móveis do Google de que o anúncio recebeu um clique.
willDismissFullScreenView	Notifica o SDK dos anúncios para dispositivos móveis do Google de que o anúncio será dispensado.
didDismissFullScreenView	Notifica o SDK dos anúncios para dispositivos móveis do Google de que o anúncio foi dispensado.