Implementar anúncios picture-in-picture (Beta)

Selecione a plataforma: Android iOS

Picture-in-picture

Os anúncios picture-in-picture (PiP) aparecem em uma janela flutuante que fica acima do conteúdo na tela, como artigos, feeds ou jogos. Esse formato permite que os usuários interajam com seu app enquanto o anúncio permanece visível. Escolha esse formato para veicular anúncios que não ocupam a tela inteira.

Este guia aborda como solicitar e mostrar anúncios picture-in-picture no seu app usando Google Mobile Ads SDK.

Antes de começar

Antes de continuar, faça o seguinte:

Carregar um anúncio

Para carregar um objeto GADPictureInPictureAd, crie uma solicitação de anúncio e chame o método load:

Swift

private func loadAdManagerPictureInPictureAd() async {
  do {
    // Capture the PictureInPictureAd reference for later use.
    pipAd = try await PictureInPictureAd.load(
      with: adUnitID, request: AdManagerRequest())
    // Set the delegate to be notified of ad events.
    pipAd?.delegate = self
  } catch {
    print(
      "Picture-in-Picture ad failed to load: \(error.localizedDescription)")
  }
}

Substitua adUnitID pelo ID do seu bloco de anúncios.

Objective-C

- (void)loadAdManagerPictureInPictureAd {
  GAMRequest *request = [GAMRequest request];

  [GADPictureInPictureAd
       loadWithAdUnitID:kAdUnitID
                request:request
      completionHandler:^(GADPictureInPictureAd *_Nullable ad, NSError *_Nullable error) {
        if (error) {
          NSLog(@"Picture-in-Picture ad failed to load: %@", error);
          return;
        }
        // Capture the PictureInPictureAd reference for later use.
        self.pipAd = ad;
        // Set the delegate to be notified of ad events.
        self.pipAd.delegate = self;
      }];
}

Substitua kAdUnitID pelo ID do seu bloco de anúncios.

Mostrar o anúncio

Para mostrar o anúncio picture-in-picture na tela, configure as opções picture-in-picture e chame o método show. O exemplo a seguir define a posição padrão do anúncio e o escopo de apresentação como a tela:

Swift

private func showPictureInPictureAd() {
  // Use the loaded PictureInPictureAd instance.
  guard let pipAd else {
    print("No ad to show.")
    return
  }
  let options = PictureInPictureAdOptions()
  // Uses the Google Mobile Ads SDK's default screen position.
  options.position = .default
  // Binds the ad lifecycle to the host screen.
  options.presentationScope = .screen

  pipAd.show(with: options)
}

Objective-C

- (void)showPictureInPictureAd {
  // Use the loaded PictureInPictureAd instance.
  if (!self.pipAd) {
    NSLog(@"No ad to show.");
    return;
  }
  GADPictureInPictureAdOptions *options =
      [[GADPictureInPictureAdOptions alloc] init];
  // Uses the Google Mobile Ads SDK's default screen position.
  options.position = GADPictureInPictureAdPositionDefault;
  // Binds the ad lifecycle to the host screen.
  options.presentationScope = GADPictureInPictureAdPresentationScopeScreen;

  [self.pipAd showWithOptions:options];
}

Definir a posição

Por padrão, o Google Mobile Ads SDK mostra um anúncio picture-in-picture no canto inferior direito da tela quando é exibido pela primeira vez ou na última posição conhecida, se já tiver sido mostrado antes. Para personalizar onde o anúncio aparece, defina a posição nas opções de picture-in-picture. O exemplo a seguir define a posição na parte de cima do conteúdo no canto superior esquerdo da tela:

Swift

private func createTopLeftPositionOptions() -> PictureInPictureAdOptions {
  let options = PictureInPictureAdOptions()
  // Sets the ad position to the top-left corner of the screen.
  options.position = .topLeft
  return options
}

Objective-C

- (GADPictureInPictureAdOptions *)createTopLeftPositionOptions {
  GADPictureInPictureAdOptions *options =
      [[GADPictureInPictureAdOptions alloc] init];
  // Sets the ad position to the top-left corner of the screen.
  options.position = GADPictureInPictureAdPositionTopLeft;
  return options;
}

Para todas as posições disponíveis, consulte GADPictureInPictureAdPosition.

Definir o escopo da apresentação

Por padrão, Google Mobile Ads SDK vincula um anúncio picture-in-picture à tela do host atual. Google Mobile Ads SDK dispensa o anúncio quando a hierarquia de visualização da tela do host não está mais na memória. Para manter o anúncio visível depois que a tela do host for removida da memória, defina o escopo de apresentação como o aplicativo:

Swift

private func createApplicationScopedOptions() -> PictureInPictureAdOptions {
  let options = PictureInPictureAdOptions()
  // Keeps the ad visible beyond the host screen's lifecycle.
  options.presentationScope = .application
  return options
}

Objective-C

- (GADPictureInPictureAdOptions *)createApplicationScopedOptions {
  GADPictureInPictureAdOptions *options =
      [[GADPictureInPictureAdOptions alloc] init];
  // Keeps the ad visible beyond the host screen's lifecycle.
  options.presentationScope = GADPictureInPictureAdPresentationScopeApplication;
  return options;
}

Para mais informações, consulte Manter o anúncio visível em várias telas.

Definir o callback de evento do anúncio

Para processar eventos de ciclo de vida de anúncios picture-in-picture, defina o callback de evento no anúncio antes de mostrá-lo. Esse callback informa eventos padrão, como cliques e impressões. Esse callback também informa eventos específicos do picture-in-picture, como quando o anúncio é mostrado ou ocultado:

Swift

func pictureInPictureAdDidShow(_ pictureInPictureAd: PictureInPictureAd) {
  print("Picture-in-Picture ad shown.")
}

func pictureInPictureAdDidHide(_ pictureInPictureAd: PictureInPictureAd) {
  print("Picture-in-Picture ad hidden.")
}

func pictureInPictureAdDidFailToShow(
  _ pictureInPictureAd: PictureInPictureAd, error: Error
) {
  print("Picture-in-Picture ad failed to show: \(error.localizedDescription)")
}

func pictureInPictureAdDidRecordImpression(
  _ pictureInPictureAd: PictureInPictureAd
) {
  print("Picture-in-Picture ad recorded an impression.")
}

func pictureInPictureAdDidRecordClick(
  _ pictureInPictureAd: PictureInPictureAd
) {
  print("Picture-in-Picture ad recorded a click.")
}

func pictureInPictureAdWillPresentScreen(
  _ pictureInPictureAd: PictureInPictureAd
) {
  print("Picture-in-Picture ad will present screen.")
}

func pictureInPictureAdWillDismissScreen(
  _ pictureInPictureAd: PictureInPictureAd
) {
  print("Picture-in-Picture ad will dismiss screen.")
}

func pictureInPictureAdDidDismissScreen(
  _ pictureInPictureAd: PictureInPictureAd
) {
  print("Picture-in-Picture ad dismissed screen.")
}

Objective-C

- (void)pictureInPictureAdDidShow:(GADPictureInPictureAd *)pictureInPictureAd {
  NSLog(@"Picture-in-Picture ad shown.");
}

- (void)pictureInPictureAdDidHide:(GADPictureInPictureAd *)pictureInPictureAd {
  NSLog(@"Picture-in-Picture ad hidden.");
}

- (void)pictureInPictureAdDidFailToShow:(GADPictureInPictureAd *)pictureInPictureAd
                              withError:(NSError *)error {
  NSLog(@"Picture-in-Picture ad failed to show: %@", error);
}

- (void)pictureInPictureAdDidRecordImpression:(GADPictureInPictureAd *)pictureInPictureAd {
  NSLog(@"Picture-in-Picture ad recorded an impression.");
}

- (void)pictureInPictureAdDidRecordClick:(GADPictureInPictureAd *)pictureInPictureAd {
  NSLog(@"Picture-in-Picture ad recorded a click.");
}

- (void)pictureInPictureAdWillPresentScreen:(GADPictureInPictureAd *)pictureInPictureAd {
  NSLog(@"Picture-in-Picture ad will present screen.");
}

- (void)pictureInPictureAdWillDismissScreen:(GADPictureInPictureAd *)pictureInPictureAd {
  NSLog(@"Picture-in-Picture ad will dismiss screen.");
}

- (void)pictureInPictureAdDidDismissScreen:(GADPictureInPictureAd *)pictureInPictureAd {
  NSLog(@"Picture-in-Picture ad dismissed screen.");
}

Ocultar o anúncio

Para remover o anúncio flutuante da tela, chame o método hide. Esse método invoca o callback de evento de anúncio oculto:

Swift

private func hidePictureInPictureAd() {
  // Use the loaded PictureInPictureAd instance.
  guard let pipAd else {
    print("No ad to hide.")
    return
  }
  pipAd.hide()
}

Objective-C

- (void)hidePictureInPictureAd {
  // Use the loaded PictureInPictureAd instance.
  if (!self.pipAd) {
    NSLog(@"No ad to hide.");
    return;
  }
  [self.pipAd hide];
}

Limpar recursos de anúncio

Para evitar vazamentos de memória, descarte a referência ao objeto de anúncio quando o app terminar de usar o anúncio. Por exemplo, quando o app não mostra ou interage mais com o anúncio. Para anúncios no escopo da tela, solte a referência quando o app remover a tela host da memória. Para anúncios no escopo do app, mantenha a referência do anúncio enquanto o usuário navega pelas telas e descarte a referência quando o usuário dispensar o anúncio:

Swift

private func cleanUpPictureInPictureAd() {
  pipAd?.hide()
  pipAd = nil
}

Objective-C

- (void)cleanUpPictureInPictureAd {
  [self.pipAd hide];
  self.pipAd = nil;
}

Manter o anúncio visível em todas as telas

Quando você define o escopo da apresentação como o aplicativo, o anúncio picture-in-picture permanece visível mesmo quando o app remove a tela de hospedagem da memória. Para interagir com o anúncio ou dispensá-lo quando o usuário sair da tela principal, seu app precisa manter o acesso ao anúncio picture-in-picture. Recomendamos manter o anúncio em um singleton no nível do app ou em um gerenciador de estado compartilhado, em vez de em uma variável de instância de uma única tela.

Para exemplos de como manter um anúncio visível em várias telas, consulte os seguintes apps de exemplo: