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 do Ad Manager a um app iOS.

Pré-requisitos

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

Sempre teste com anúncios de teste

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

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

/21775744923/example/rewarded

Ele foi configurado especialmente para retornar anúncios de teste para cada solicitação, e você pode usá-lo nos seus próprios apps durante a programação, o teste e a depuração. Basta substituí-lo pelo seu 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 premiados são as seguintes:

• Carregar um anúncio
• [Opcional] Validar callbacks de SSV
• Registrar callbacks
• Mostrar o anúncio e processar o evento de recompensa

Carregar um anúncio

É possível carregar um anúncio usando o método load(adUnitID:request) na classe GADRewardedAd.

Swift

import GoogleMobileAds
import UIKit

class ViewController: UIViewController {

  private var rewardedAd: GADRewardedAd?

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

SwiftUI

import GoogleMobileAds

class RewardedViewModel: NSObject, ObservableObject, GADFullScreenContentDelegate {
  @Published var coins = 0
  private var rewardedAd: GADRewardedAd?

  func loadAd() async {
    do {
      rewardedAd = try await GADRewardedAd.load(
        withAdUnitID: "ca-app-pub-3940256099942544/1712485313", request: GADRequest())
      rewardedAd?.fullScreenContentDelegate = self
    } catch {
      print("Failed to load rewarded ad with error: \(error.localizedDescription)")
    }
  }
RewardedViewModel.swift

Objective-C

@import GoogleMobileAds;
@import UIKit;

@interface ViewController ()

@property(nonatomic, strong) GADRewardedAd *rewardedAd;

@end

@implementation ViewController
- (void)loadRewardedAd {
  GAMRequest *request = [GAMRequest request];
  [GADRewardedAd
      loadWithAdUnitID:@"/21775744923/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 carregados antes de exibi-los, para que eles possam ser mostrados sem latência quando necessário. Como os anúncios expiram após uma hora, limpe esse cache e recarregue com novos anúncios a cada hora.

[Opcional] Validar callbacks de verificação do lado do servidor (SSV, na sigla em inglês)

Os apps que exigem dados extras em callbacks de verificação 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 para o 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 será apresentado no callback de SSV.

O exemplo de código abaixo 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: "/21775744923/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:@"/21775744923/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 recompensa personalizada a qualquer momento.

Importante: a string de recompensa personalizada é escapada por porcentagem e pode exigir decodificação quando analisada pelo callback de SSV.

Registrar callbacks

Para receber notificações sobre 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 ou sem sucesso e quando é dispensado. O código abaixo 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() async {
    do {
      rewardedAd = try await GADRewardedAd.load(
        withAdUnitID: "/21775744923/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.")
  }
}

SwiftUI

Atribua a propriedade fullScreenContentDelegate ao anúncio retornado:

rewardedAd?.fullScreenContentDelegate = self
RewardedViewModel.swift

Implemente o protocolo:

func adDidRecordImpression(_ ad: GADFullScreenPresentingAd) {
  print("\(#function) called")
}

func adDidRecordClick(_ ad: GADFullScreenPresentingAd) {
  print("\(#function) called")
}

func ad(
  _ ad: GADFullScreenPresentingAd,
  didFailToPresentFullScreenContentWithError error: Error
) {
  print("\(#function) called")
}

func adWillPresentFullScreenContent(_ ad: GADFullScreenPresentingAd) {
  print("\(#function) called")
}

func adWillDismissFullScreenContent(_ ad: GADFullScreenPresentingAd) {
  print("\(#function) called")
}

func adDidDismissFullScreenContent(_ ad: GADFullScreenPresentingAd) {
  print("\(#function) called")
  // Clear the rewarded ad.
  rewardedAd = nil
}
RewardedViewModel.swift

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, depois que um anúncio premiado é exibido, ele não pode ser mostrado novamente. A prática recomendada é carregar outro anúncio premiado no método adDidDismissFullScreenContent: em GADFullScreenContentDelegate para que o próximo anúncio premiado comece a carregar assim que o anterior for descartado.

Mostrar o anúncio e processar o evento de recompensa

Antes de mostrar um anúncio premiado aos usuários, é necessário apresentar uma opção explícita para que eles assistam o conteúdo do anúncio premiado em troca de uma recompensa. Os anúncios premiados precisam ser uma experiência ativada pelo usuário.

Ao apresentar seu anúncio, forneça um objeto GADUserDidEarnRewardHandler para processar a recompensa do usuário.

O código a seguir apresenta o melhor método para mostrar 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.
  }
}

SwiftUI

Detecte eventos da interface no visualizador para determinar quando mostrar o anúncio.

var body: some View {
  VStack(spacing: 20) {
      Button("Watch video for additional 10 coins") {
        viewModel.showAd()
        showWatchVideoButton = false
      }
RewardedContentView.swift

Apresente o anúncio premiado do modelo de visualização:

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

  rewardedAd.present(fromRootViewController: nil) {
    let reward = rewardedAd.adReward
    print("Reward amount: \(reward.amount)")
    self.addCoins(reward.amount.intValue)
  }
}
RewardedViewModel.swift

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 saber os detalhes da recompensa do GADRewardedAd?

Sim, se você precisar do valor da recompensa antes que o callback userDidEarnReward seja acionado, o GADRewardedAd tem uma propriedade adReward que pode ser verificada para verificar o valor da recompensa depois que o anúncio for carregado.

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

Depois de 10 segundos, o SDK dos anúncios para dispositivos móveis do Google invoca o GADInitializationCompletionHandler fornecido 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úncio nessa sessão.

É possível continuar a consultar o status de inicialização de todos os adaptadores durante a sessão do app chamando GADMobileAds.initializationStatus.

Como descobrir por que uma rede de mediação específica não está pronta?

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

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

Para 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 rede de publicidade que oferecem um único método de delegação com informações de recompensa, o adaptador de mediação invocou userDidEarnRewardHandler antes de adDidDismissFullScreenContent:.

Exemplos no GitHub

Confira os exemplos completos de anúncios premiados no seu idioma preferido:

• Swift
• SwiftUI
• Objective-C

Próximas etapas

Saiba mais sobre a privacidade do usuário.