Anúncios premiados

Os anúncios premiados são aqueles com que os usuários podem interagir em troca de recompensas no app. Este guia mostra como integrar anúncios premiados de Ad Managera um app iOS.

Pré-requisitos

• SDK dos anúncios para dispositivos móveis do Google 8.0.0 ou mais recente.
• Leia o Guia explicativo.

Sempre faça testes com anúncios de teste

Ao criar e testar seus apps, use anúncios de teste em vez de anúncios de produção ativos. Sua conta poderá ser suspensa se isso não for feito.

A maneira mais fácil de carregar anúncios de teste é usar nosso ID de bloco de anúncios de teste dedicado para anúncios premiados do iOS:

/6499/example/rewarded

Ele foi configurado especialmente para retornar anúncios de teste para cada solicitação. Você pode usá-lo nos seus próprios apps durante a programação, o teste e a depuração. Apenas lembre-se de substituí-lo pelo seu próprio ID de bloco de anúncios antes de publicar o app.

Para mais informações sobre como os anúncios de teste do SDK para dispositivos móveis funcionam, consulte Anúncios de teste.

Implementação

As principais etapas para integrar anúncios intersticiais premiados são:

• Carregar um anúncio
• [Opcional] Valide os callbacks de SSV
• Registrar-se para callbacks
• Exiba o anúncio e processe o evento de recompensa.

Carregar um anúncio

É possível carregar um anúncio usando o método estático loadWithAdUnitID:request:completionHandler: na classe GADRewardedAd. O método de carregamento requer o ID do bloco de anúncios, um objeto GAMRequest e um gerenciador de conclusão, que é chamado quando o carregamento do anúncio é concluído ou apresenta falha. O objeto GADRewardedAd carregado é fornecido como um parâmetro no gerenciador de conclusão. O exemplo abaixo mostra como carregar um GADRewardedAd na classe ViewController.

Swift

import GoogleMobileAds
import UIKit

class ViewController: UIViewController {

  private var rewardedAd: GADRewardedAd?

  func loadRewardedAd() {
    do {
      rewardedAd = try await GADRewardedAd.load(
        withAdUnitID: "/6499/example/rewarded", request: GAMRequest())
    } catch {
      print("Rewarded ad failed to load with error: \(error.localizedDescription)")
    }
  }
}

Objective-C

@import GoogleMobileAds;
@import UIKit;

@interface ViewController ()

@property(nonatomic, strong) GADRewardedAd *rewardedAd;

@end

@implementation ViewController
- (void)loadRewardedAd {
  GAMRequest *request = [GAMRequest request];
  [GADRewardedAd
      loadWithAdUnitID:@"/6499/example/rewarded"
                request:request
      completionHandler:^(GADRewardedAd *ad, NSError *error) {
        if (error) {
          NSLog(@"Rewarded ad failed to load with error: %@", [error localizedDescription]);
          return;
        }
        self.rewardedAd = ad;
        NSLog(@"Rewarded ad loaded.");
      }];
}

Dica:é possível usar chamadas de carregamento de anúncios para criar um cache de anúncios pré-carregados antes da exibição deles. Assim, os anúncios poderão ser exibidos com latência zero, quando necessário. Como os anúncios expiram após uma hora, limpe esse cache e atualize a página com novos anúncios a cada hora.

[Opcional] Validar os callbacks de verificação do lado do servidor (SSV)

Apps que exigem dados extras em callbacks de verificação do lado do servidor precisam usar o recurso de dados personalizados dos anúncios premiados. Qualquer valor de string definido em um objeto de anúncio premiado é transmitido ao parâmetro de consulta custom_data do callback de SSV. Se nenhum valor de dados personalizado for definido, o valor do parâmetro de consulta custom_data não estará presente no callback SSV.

O exemplo de código a seguir demonstra como definir dados personalizados em um objeto de anúncio premiado antes de solicitar um anúncio.

Swift

do {
  rewardedAd = try await GADRewardedAd.load(
    withAdUnitID: "/6499/example/rewarded", request: GAMRequest())
  let options = GADServerSideVerificationOptions()
  options.customRewardString = "SAMPLE_CUSTOM_DATA_STRING"
  rewardedAd.serverSideVerificationOptions = options
} catch {
  print("Rewarded ad failed to load with error: \(error.localizedDescription)")
}

Objective-C

[GADRewardedAd
     loadWithAdUnitID:@"/6499/example/rewarded"
              request:[GAMRequest request];
    completionHandler:^(GADRewardedAd *ad, NSError *error) {
      if (error) {
        // Handle Error
        return;
      }
      self.rewardedAd = ad;
      GADServerSideVerificationOptions *options =
          [[GADServerSideVerificationOptions alloc] init];
      options.customRewardString = @"SAMPLE_CUSTOM_DATA_STRING";
      ad.serverSideVerificationOptions = options;
    }];

Importante: a partir da versão 7.50.0 do SDK, é possível definir a string de prêmio personalizada a qualquer momento.

Importante:a string de prêmio personalizada tem escape de porcentagem e pode exigir decodificação quando analisada do callback de SSV.

Registrar-se para callbacks

Para receber notificações de eventos de apresentação, implemente o protocolo GADFullScreenContentDelegate e atribua-o à propriedade fullScreenContentDelegate do anúncio retornado. O protocolo GADFullScreenContentDelegate processa callbacks para quando o anúncio é apresentado com sucesso ou não e quando ele é dispensado. O código a seguir mostra como implementar o protocolo e atribuí-lo ao anúncio:

Swift

import GoogleMobileAds
import UIKit

class ViewController: UIViewController, GADFullScreenContentDelegate {

  private var rewardedAd: GADRewardedAd?

  func loadRewardedAd() {
    do {
      rewardedAd = try await GADRewardedAd.load(
        withAdUnitID: "/6499/example/rewarded", request: GAMRequest())
      rewardedAd?.fullScreenContentDelegate = self
    } catch {
      print("Rewarded ad failed to load with error: \(error.localizedDescription)")
    }
  }

  /// Tells the delegate that the ad failed to present full screen content.
  func ad(_ ad: GADFullScreenPresentingAd, didFailToPresentFullScreenContentWithError error: Error) {
    print("Ad did fail to present full screen content.")
  }

  /// Tells the delegate that the ad will present full screen content.
  func adWillPresentFullScreenContent(_ ad: GADFullScreenPresentingAd) {
    print("Ad will present full screen content.")
  }

  /// Tells the delegate that the ad dismissed full screen content.
  func adDidDismissFullScreenContent(_ ad: GADFullScreenPresentingAd) {
    print("Ad did dismiss full screen content.")
  }
}

Objective-C

@interface ViewController () <GADFullScreenContentDelegate>

@property(nonatomic, strong) GADRewardedAd *rewardedAd;

@end

@implementation ViewController
- (void)loadRewardedAd {
  GAMRequest *request = [GAMRequest request];
  [GADRewardedAd
      loadWithAdUnitID:@"ca-app-pub-3940256099942544/4806952744"
                request:request
      completionHandler:^(GADRewardedAd *ad, NSError *error) {
        if (error) {
          NSLog(@"Rewarded ad failed to load with error: %@", [error localizedDescription]);
          return;
        }
        self.rewardedAd = ad;
        NSLog(@"Rewarded ad loaded.");
        self.rewardedAd.fullScreenContentDelegate = self;
      }];
}

/// Tells the delegate that the ad failed to present full screen content.
- (void)ad:(nonnull id<GADFullScreenPresentingAd>)ad
    didFailToPresentFullScreenContentWithError:(nonnull NSError *)error {
    NSLog(@"Ad did fail to present full screen content.");
}

/// Tells the delegate that the ad will present full screen content.
- (void)adWillPresentFullScreenContent:(nonnull id<GADFullScreenPresentingAd>)ad {
    NSLog(@"Ad will present full screen content.");
}

/// Tells the delegate that the ad dismissed full screen content.
- (void)adDidDismissFullScreenContent:(nonnull id<GADFullScreenPresentingAd>)ad {
    NSLog(@"Ad did dismiss full screen content.");
}

GADRewardedAd é um objeto de uso único. Isso significa que, uma vez que um anúncio premiado é exibido, não pode ser mostrado novamente. Uma prática recomendada é carregar outro anúncio premiado no método adDidDismissFullScreenContent: em GADFullScreenContentDelegate para que o próximo anúncio premiado comece a ser carregado assim que o anterior for dispensado.

Exiba o anúncio e processe o evento de recompensa.

Antes de exibir um anúncio premiado, é necessário apresentar ao usuário uma opção explícita de visualizar o conteúdo do anúncio premiado em troca de uma recompensa. Os anúncios premiados precisam ser sempre uma experiência opcional.

Ao apresentar seu anúncio, você precisa fornecer um objeto GADUserDidEarnRewardHandler para processar a recompensa para o usuário.

O código a seguir apresenta o melhor método para exibir um anúncio premiado.

Swift

func show() {
  guard let rewardedAd = rewardedAd else {
    return print("Ad wasn't ready.")
  }

  // The UIViewController parameter is an optional.
  ad.present(fromRootViewController: nil) {
    let reward = ad.adReward
    print("Reward received with currency \(reward.amount), amount \(reward.amount.doubleValue)")
    // TODO: Reward the user.
  }
}

Objective-C

- (void)show {
  if (self.rewardedAd) {
    // The UIViewController parameter is nullable.
    [self.rewardedAd presentFromRootViewController:nil
                                  userDidEarnRewardHandler:^{
                                  GADAdReward *reward =
                                      self.rewardedAd.adReward;
                                  // TODO: Reward the user!
                                }];
  } else {
    NSLog(@"Ad wasn't ready");
  }
}

Perguntas frequentes

Posso acessar os detalhes do prêmio para GADRewardedAd?

Sim, se você precisar do valor da recompensa antes que o callback userDidEarnReward seja disparado, GADRewardedAd tem uma propriedade adReward que você pode conferir para conferir o valor da recompensa após o carregamento do anúncio.

Há um tempo limite para a chamada de inicialização?

Após 10 segundos, o SDK dos anúncios para dispositivos móveis do Google invoca a GADInitializationCompletionHandler fornecida ao método startWithCompletionHandler:, mesmo que uma rede de mediação ainda não tenha concluído a inicialização.

E se algumas redes de mediação não estiverem prontas quando eu receber o callback de inicialização?

Recomendamos carregar um anúncio dentro do GADInitializationCompletionHandler. Mesmo que uma rede de mediação não esteja pronta, o SDK dos anúncios para dispositivos móveis do Google ainda solicita um anúncio a essa rede. Portanto, se uma rede de mediação terminar a inicialização após o tempo limite, ela ainda poderá atender futuras solicitações de anúncios nessa sessão.

Você pode continuar pesquisando o status de inicialização de todos os adaptadores durante a sessão do app chamando GADMobileAds.initializationStatus.

Como faço para descobrir por que uma determinada rede de mediação não está pronta?

A propriedade description de um objeto GADAdapterStatus descreve por que um adaptador não está pronto para atender a solicitações de anúncios.

O gerenciador de conclusão userDidEarnRewardHandler sempre é chamado antes do método delegado adDidDismissFullScreenContent:?

Para os anúncios do Google, todas as chamadas userDidEarnRewardHandler ocorrem antes de adDidDismissFullScreenContent:. Para anúncios veiculados por mediação, a implementação do SDK da rede de publicidade de terceiros determina a ordem do callback. Para SDKs de redes de publicidade que fornecem um único método delegado com informações de recompensa, o adaptador de mediação invoca userDidEarnRewardHandler antes de adDidDismissFullScreenContent:.

Exemplos no GitHub

• Exemplo de anúncios premiados: Swift | Objective-C

Próximas etapas

Saiba mais sobre a privacidade do usuário.