Anúncios premiados

Os anúncios premiados são aqueles com que os usuários podem interagir em troca da para recompensas no app. Este guia mostra como integrar anúncios premiados do Ad Manager em 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 iOS anúncios premiados:

/21775744923/example/rewarded

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

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

Implementação

Confira a seguir as principais etapas para integrar os anúncios premiados:

• Carregar um anúncio
• [Opcional] Validar 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 a 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: Você pode usar chamadas de carregamento de anúncios para criar um cache de anúncios pré-carregados antes de pretende exibi-los para que eles possam aparecer com latência zero, quando necessário. Como os anúncios expiram após uma hora, limpe esse cache e atualize com as novas anúncios por hora.

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

Apps que exigem dados extras no lado do servidor retornos de chamada de verificação devem usar o método recurso de dados personalizados dos anúncios premiados. Qualquer valor de string definido em um anúncio premiado é transmitido ao parâmetro de consulta custom_data do callback SSV. Em caso negativo valor de dados personalizado estiver definido, o valor do parâmetro de consulta custom_data não será presentes no retorno de chamada de SSV.

O exemplo de código a seguir demonstra como definir dados personalizados em um 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 prêmio personalizada em qualquer

Importante: a string de recompensa personalizada é percentual. com escape e podem exigir decodificação quando analisado a partir do callback SSV.

Registrar-se para callbacks

Para receber notificações de eventos de apresentação, você deve implementar o protocolo GADFullScreenContentDelegate e atribuí-lo à fullScreenContentDelegate do anúncio retornado. A o protocolo GADFullScreenContentDelegate processa callbacks para quando o anúncio apresenta com sucesso ou não e quando é dispensado. O seguinte 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, assim que um anúncio premiado for mostrado, ele não pode ser mostrado novamente. Uma prática recomendada é carregar outro anúncio premiado no método adDidDismissFullScreenContent: da GADFullScreenContentDelegate para que o próximo anúncio premiado comece a carregar assim que o anterior for dispensada.

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

Antes de exibir um anúncio premiado, você precisa apresentar a eles escolha explícita de visualizar o conteúdo do anúncio premiado em troca de uma recompensa. Premiado os anúncios devem sempre ser uma experiência opcional.

Ao apresentar seu anúncio, você precisa fornecer um objeto GADUserDidEarnRewardHandler de lidar com 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.
  }
}

SwiftUI

Ouça eventos de interface na visualização 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 no 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 acessar os detalhes do prêmio para GADRewardedAd?

Sim, se você precisar do valor da recompensa antes do callback userDidEarnReward for acionado, GADRewardedAd tem um adReward que pode ser verificada para confirmar o valor da recompensa após o carregamento do anúncio.

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 startWithCompletionHandler:, mesmo que uma rede de mediação concluiu 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 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. Então, se uma rede de mediação termina a inicialização após o tempo limite, ela ainda pode atender futuras solicitações de anúncios na sessão.

Você pode continuar a consultar o status de inicialização de todos os adaptadores 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 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 de userDidEarnRewardHandler ocorrem antes de adDidDismissFullScreenContent:. Para anúncios veiculados por mediação, a rede de publicidade de terceiros A implementação do SDK determina a ordem do callback. Para SDKs de redes de publicidade que forneça um único método delegado com informações do prêmio, o adaptador de mediação invoca userDidEarnRewardHandler antes de adDidDismissFullScreenContent:.

Exemplos no GitHub

Confira os exemplos completos de anúncios premiados no idioma de sua preferência:

• Swift
• SwiftUI
• Objective-C

Próximas etapas

Saiba mais sobre a privacidade do usuário.