Desenvolvimento do adaptador de mediação da rede de anúncios

Observação :o uso do SDK dos anúncios para dispositivos móveis do Google com relação aos Serviços de Mediação é regido pelos Termos de Serviço da Mediação.

Este guia destina-se a redes de anúncios que procuram criar um adaptador de mediação. Se você é um editor, consulte as instruções de mediação do editor.

Um adaptador de mediação é a camada de comunicação entre sua rede de publicidade e a Mediação de anúncios para dispositivos móveis do Google. Os adaptadores veiculam anúncios da sua rede de anúncios, enquanto encaminham eventos de anúncios relevantes à AdMob. Um adaptador é responsável por implementar o protocolo GADMAdNetworkAdapter para garantir que ele forneça os recursos necessários.

Pré-requisitos

• Xcode 15.3 ou mais recente
• Meta de implantação de 8.0 ou mais recente
• Outros cabeçalhos da pasta "Mediation Adapters" do SDK dos anúncios para dispositivos móveis do Google para iOS

Sua rede de publicidade precisa ter uma relação de trabalho estabelecida com o Google para criar um adaptador de mediação.

Exemplo de rede de anúncios

Este guia demonstra como criar um adaptador para a rede de anúncios de amostra. O SDK de rede de anúncios de amostra contém classes que representam as classes oferecidas pela maioria das redes de anúncios:

@interface SampleBanner : UILabel

@property(nonatomic, copy) NSString *adUnit;
@property(nonatomic, weak) id<SampleBannerAdDelegate> delegate;
- (void)fetchAd:(SampleAdRequest *)request;

@end

typedef NS_ENUM(NSInteger, SampleErrorCode) {
  SampleErrorCodeBadRequest = 0,
  SampleErrorCodeUnknown = 1,
  SampleErrorCodeNetworkError = 2,
  SampleErrorCodeNoInventory = 3,
};

@interface SampleAdRequest : NSObject

@property(nonatomic, assign) BOOL testMode;
@property(nonatomic, copy) NSArray *keywords;

@end

@interface SampleInterstitial : NSObject

@property(nonatomic, copy) NSString *adUnit;
@property(nonatomic, weak) id<SampleInterstitialAdDelegate> delegate;
@property(nonatomic, assign, getter=isInterstitialLoaded) BOOL interstitialLoaded;
- (void)fetchAd:(SampleAdRequest *)request;
- (void)show;

@end

@protocol SampleBannerAdDelegate
- (void)bannerDidLoad:(SampleBanner *)banner;
- (void)banner:(SampleBanner *)banner didFailToLoadAdWithError:(SampleErrorCode)error;
- (void)bannerWillLeaveApplication:(SampleBanner *)banner;

@end

@protocol SampleInterstitialAdDelegate<NSObject>
- (void)interstitialDidLoad:(SampleInterstitial *)interstitial;
- (void)interstitial:(SampleInterstitial *)interstitial
    didFailToLoadAdWithError:(SampleErrorCode)error;
- (void)interstitialWillPresentScreen:(SampleInterstitial *)interstitial;
- (void)interstitialWillDismissScreen:(SampleInterstitial *)interstitial;
- (void)interstitialDidDismissScreen:(SampleInterstitial *)interstitial;
- (void)interstitialWillLeaveApplication:(SampleInterstitial *)interstitial;

@end

Veja a implementação completa do SDK de exemplo para mais informações sobre essas classes.

Conector

Os adaptadores de mediação interagem com o SDK dos anúncios para dispositivos móveis do Google usando um objeto que implementa o protocolo GADMAdNetworkConnector. A partir daqui, chamaremos esse objeto de conector. Ele expõe informações necessárias para solicitações de anúncios e fornece um meio de chamar a mediação para eventos de anúncios e interações do usuário. O conector é fornecido aos adaptadores de mediação no momento da inicialização. Configure o adaptador para armazenar o conector em uma variável de instância:

- (id)initWithGADMAdNetworkConnector:(id<GADMAdNetworkConnector>)c {
  if ((self = [super init])) {
    _connector = c;
  }
  return self;
}

Parâmetros do servidor

Sua rede de publicidade provavelmente precisa de identificadores para identificar um editor. A rede de anúncios de amostra, por exemplo, exige um bloco de anúncios. Esses parâmetros obrigatórios do servidor são fornecidos ao adaptador pelo método credentials, que retorna um NSDictionary de identificadores e valores correspondentes. A linha de código a seguir recupera o parâmetro de servidor chamado ad_unit para a rede de anúncios de amostra do conector:

self.interstitialAd.adUnit = [[self.connector credentials] objectForKey:@"ad_unit"];

Configuração da rede de mediação

As redes de publicidade precisam informar a AdMob sobre os parâmetros de servidor necessários para a rede delas. Isso permite que a AdMob configure sua rede no front-end.

Ao ativar sua rede para mediação no front-end, a AdMob exige que você insira os valores necessários para instanciar o adaptador. A captura de tela abaixo mostra que um identificador de posicionamento do aplicativo (APID, na sigla em inglês) é necessário para a Millennial Media e um ID do app é necessário para a InMobi.

Confira este artigo para mais informações sobre como configurar redes de anúncios de mediação.

Fazer uma solicitação de anúncio de mediação

Solicitação de banner

Nas solicitações de banner de mediação, o método getBannerWithSize é chamado logo após o adaptador ser instanciado. Esse método não retorna nada. Ele sinaliza ao adaptador para iniciar uma busca assíncrona de anúncios na rede. Faça com que o adaptador detecte callbacks para o SDK. Se o SDK não oferecer suporte ao tamanho do anúncio especificado ou não for compatível com anúncios de banner, invoque o método adapter:didFailAd: no conector.

Uma implementação de getBannerWithSize para a rede de anúncios de amostra fica assim:

- (void)getBannerWithSize:(GADAdSize)adSize {
  //The adapter should fail immediately if the adSize is not supported
  if (!GADAdSizeEqualToSize(adSize, GADAdSizeBanner) &&
      !GADAdSizeEqualToSize(adSize, GADAdSizeMediumRectangle) &&
      !GADAdSizeEqualToSize(adSize, GADAdSizeFullBanner) &&
      !GADAdSizeEqualToSize(adSize, GADAdSizeLeaderboard)) {
    NSString *errorDesc =
        [NSString stringWithFormat:@"Invalid ad type %@, not going to get ad.",
                                   NSStringFromGADAdSize(adSize)];
    NSDictionary *errorInfo = [NSDictionary
        dictionaryWithObjectsAndKeys:errorDesc, NSLocalizedDescriptionKey, nil];
    NSError *error = [NSError errorWithDomain:GADErrorDomain
                                         code:GADErrorMediationInvalidAdSize
                                     userInfo:errorInfo];
    [self.connector adapter:self didFailAd:error];
    return;
  }
  self.bannerAd = [[SampleBanner alloc]
      initWithFrame:CGRectMake(0, 0, adSize.size.width, adSize.size.height)];

  self.bannerAd.delegate = self;
  self.bannerAd.adUnit = [[self.connector credentials] objectForKey:@"ad_unit"];

  // Setup request parameters.
  SampleAdRequest *request = [[SampleAdRequest alloc] init];
  request.testMode = self.connector.testMode;
  request.keywords = self.connector.userKeywords;
  [self.bannerAd fetchAd:request];
  NSLog(@"Requesting banner from Sample Ad Network");
}

Outros parâmetros de segmentação

O conector contém algumas informações de segmentação comuns que você pode consultar para a segmentação de anúncios:

• userKeywords
• testMode
• childDirectedTreatment

Extras de mediação

Os extras de mediação permitem que sua rede de publicidade ofereça suporte a parâmetros de segmentação ou entradas extras que não são cobertas pelos parâmetros de solicitação adicionais fornecidos pelo conector. Essa funcionalidade pode ser fornecida por uma classe que implementa o protocolo GADAdNetworkExtras. A classe SampleAdNetworkExtras é mostrada abaixo como um exemplo:

@interface SampleAdNetworkExtras : NSObject <GADAdNetworkExtras>
/// Should ad volume audio be muted.
@property(nonatomic, assign) BOOL muteAudio;

@end

Os editores precisam transmitir uma instância da subclasse GADAdNetworkExtras ao fazer uma solicitação de anúncio. Essa instância da subclasse GADAdNetworkExtras pode ser acessada pelo conector. Veja como você pode usar os extras de mediação ao criar uma solicitação de anúncio para sua rede:

SampleAdRequest *request = [[SampleAdRequest alloc] init];
SampleAdNetworkExtras *myAdNetworkExtras = [self.connector networkExtras];
request.muteAudio = myAdNetworkExtras.muteAudio;
[self.bannerAd fetchAd:request];

Para garantir que a subclasse GADAdNetworkExtras possa ser acessada pelo conector, implemente networkExtrasClass e retorne a subclasse GADAdNetworkExtras:

+ (Class<GADAdNetworkExtras>)networkExtrasClass {
  return [SampleAdNetworkExtras class];
}

Se o adaptador não usar extras de mediação, o método networkExtrasClass retornará Nil.

Notificar mediação

O adaptador deve implementar o listener de anúncios na sua rede e encaminhar os callbacks de eventos de anúncio relevantes pelo conector. A tabela abaixo explica quando chamar cada método delegado:

Método	Quando ligar
adapter:didReceiveAdView:	A solicitação do banner foi concluída.
adapter:didFailAd:	Falha na solicitação do banner.
adapterDidGetAdClick:	O banner foi clicado.
adapterWillPresentFullScreenModal:	O banner vai apresentar uma sobreposição no app.
adapterWillDismissFullScreenModal:	A sobreposição no app será fechada.
adapterDidDismissFullScreenModal:	A sobreposição no app foi fechada.
adapterWillLeaveApplication:	O aplicativo será colocado em segundo plano ou será encerrado porque o usuário clicou em um anúncio que iniciará outro aplicativo.

O exemplo a seguir implementa a interface SampleBannerAdDelegate da rede de anúncios de amostra para encaminhar mensagens de erro e status:

- (void)bannerDidLoad:(SampleBanner *)banner {
  [self.connector adapter:self didReceiveAdView:banner];
}

- (void)banner:(SampleBanner *)banner didFailWithError:(SampleErrorCode)error {
  [self.connector adapter:self
                didFailAd:[NSError errorWithDomain:@"Ad request failed"
                                              code:error
                                          userInfo:nil]];
}

- (void)bannerWillLeaveApplication:(SampleBanner *)banner {
  [self.connector adapterDidGetAdClick:self];
  [self.connector adapterWillLeaveApplication:self];
}

Iniciar sobreposição no app x aplicativo externo

Quando um banner recebe um clique, o anúncio pode abrir uma sobreposição de tela cheia ou um aplicativo externo (como o Safari ou a app store). Os callbacks do conector que serão invocados nesses dois casos são diferentes.

Se o clique no banner abrir uma sobreposição em tela cheia, chame adapterWillPresentFullScreenModal: ao apresentar a sobreposição. Quando a sobreposição estiver fechada, chame adapterWillDismissFullScreenModal: e adapterDidDismissFullScreenModal:.

Se o clique em um banner (ou um clique em uma sobreposição de tela cheia) fizer com que o usuário saia do aplicativo, invoque o callback adapterWillLeaveApplication:.

Agora você tem um adaptador de mediação para banners funcionando. Para consultar uma implementação completa do SampleAdapter, acesse o GitHub (em inglês).

Implementar um adaptador intersticial

A implementação do adaptador para anúncios intersticiais é semelhante à dos anúncios de banner. O método getInterstitial é chamado imediatamente após o adaptador ser instanciado. Esse método não retorna nada. Espera-se que o adaptador inicie uma busca assíncrona de anúncios na rede. Faça com que o adaptador atue como um delegado ao SDK para detectar callbacks. Se o SDK não aceitar anúncios intersticiais, invoque o método adapter:didFailAd: do conector da seguinte maneira:

- (void)getInterstitial {
  self.interstitialAd = [[SampleInterstitial alloc] init];
  self.interstitialAd.delegate = self;
  self.interstitialAd.adUnit =
      [[self.connector credentials] objectForKey:@"ad_unit"];

  SampleAdRequest *request = [[SampleAdRequest alloc] init];
  // Setup request parameters.
  request.testMode = self.connector.testMode;
  request.keywords = self.connector.userKeywords;

  [self.interstitialAd fetchAd:request];
  NSLog(@"Requesting interstitial from Sample Ad Network");
}

Assim como no MediationBannerAdapter, você pode receber informações de identificação do editor e segmentação de anúncios do conector.

Notificar mediação

O adaptador deve implementar o representante de anúncios para sua rede e encaminhar os callbacks de eventos de anúncio relevantes pelo conector. A tabela abaixo explica quando chamar cada método delegado:

Método	Quando ligar
adapterDidReceiveInterstitial:	A solicitação do intersticial foi concluída.
adapter:didFailInterstitial:	A solicitação do intersticial falhou.
adapterDidGetAdClick:	O intersticial foi clicado.
adapterWillPresentInterstitial:	O intersticial será exibido.
adapterWillDismissInterstitial:	O intersticial será dispensado.
adapterDidDismissInterstitial:	O intersticial foi dispensado.
adapterWillLeaveApplication:	O aplicativo ficará em segundo plano ou será encerrado porque o usuário clicou em um anúncio que iniciará outro aplicativo.

O exemplo a seguir implementa a interface SampleInterstitialAdDelegate da rede de anúncios de amostra para encaminhar mensagens de erro e status:

- (void)interstitialDidLoad:(SampleInterstitial *)interstitial {
  [self.connector adapterDidReceiveInterstitial:self];
}

- (void)interstitial:(SampleInterstitial *)interstitial
    didFailWithError:(SampleErrorCode)error {
  [self.connector adapter:self
      didFailInterstitial:[NSError errorWithDomain:@"Ad request failed"
                                              code:error
                                          userInfo:nil]];
}

- (void)interstitialWillPresentScreen:(SampleInterstitial *)interstitial {
  [self.connector adapterWillPresentInterstitial:self];
}

- (void)interstitialWillDismissScreen:(SampleInterstitial *)interstitial {
  [self.connector adapterWillDismissInterstitial:self];
}

- (void)interstitialDidDismissScreen:(SampleInterstitial *)interstitial {
  [self.connector adapterDidDismissInterstitial:self];
}

Apresentar um intersticial

Quando o adaptador chamar adapterDidReceiveInterstitial, faça com que ele aguarde para mostrar o intersticial até que presentInterstitialFromRootViewController seja chamado. O desenvolvedor do app decide quando exibir o intersticial, que pode ser vários minutos depois de ele ter sido recebido.

Confira uma implementação de presentInterstitialFromRootViewController: para a rede de anúncios de amostra:

- (void)presentInterstitialFromRootViewController:
    (UIViewController *)rootViewController {
  if ([self.interstitialAd isLoaded]) {
    [self.interstitialAd show];
  }
}

Seu adaptador de mediação está pronto para processar anúncios intersticiais. Para referência, uma implementação completa do SampleAdapter pode ser encontrada no GitHub.

Perguntas frequentes

Devo incluir o adaptador como parte da minha biblioteca do SDK ou como uma biblioteca separada?

Recomendamos incluir o adaptador como parte da biblioteca do SDK para que os desenvolvedores precisem referenciar apenas uma biblioteca para incorporar a rede.

O que devo fazer se meu adaptador só for compatível com anúncios de banner?

Se o adaptador só for compatível com banners, faça com que ele encaminhe um evento de erro para a mediação para solicitações de intersticiais:

- (void)getInterstitial {
  NSDictionary *errorInfo = @{ NSLocalizedDescriptionKey : @"Some error" };
  NSError *error = [NSError errorWithDomain:GADErrorDomain
                                       code:GADErrorInvalidRequest
                                   userInfo:errorInfo];
  [self.connector adapter:self didFailInterstitial:error];
  return;
}

O que devo fazer se meu adaptador só for compatível com anúncios intersticiais?

Se o adaptador só é compatível com intersticiais, ele precisa encaminhar um evento de erro à mediação para solicitações de banner:

- (void)getBannerWithSize:(GADAdSize)adSize {
  NSDictionary *errorInfo = @{ NSLocalizedDescriptionKey : @"Some error" };
  NSError *error =
      [NSError errorWithDomain:GADErrorDomain
                          code:GADErrorInvalidRequest
                      userInfo:errorInfo];
  [self.connector adapter:self didFailAd:error];
  return;
}