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

Selecione a plataforma: Android iOS

Picture-in-picture

Os anúncios picture-in-picture são mostrados em uma janela flutuante que fica sobre o conteúdo na tela, como artigos, feeds ou gameplay. Esse formato permite que os usuários interajam com o app enquanto o anúncio permanecer visível. Para mostrar anúncios que não ocupam a tela inteira, escolha esse formato.

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.

Veicular o anúncio

Para mostrar o anúncio picture-in-picture na tela, configure as respectivas opções e chame o método show. O exemplo abaixo define a posição padrão do anúncio e o escopo de apresentação para 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 aparece pela primeira vez, ou na última posição conhecida, se já tiver sido mostrado. Para personalizar onde o anúncio aparece, defina a posição nas opções de picture-in-picture. O exemplo abaixo 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 ver todas as posições disponíveis, consulte GADPictureInPictureAdPosition.

Definir o escopo da apresentação

Por padrão, o Google Mobile Ads SDK vincula um anúncio picture-in-picture à tela do host atual. O Google Mobile Ads SDK dispensa o anúncio quando a hierarquia de visualização da tela 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 para 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 todas as telas.

Definir o callback do evento de 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, remova a referência ao objeto de anúncio quando o app terminar de usá-lo. Por exemplo, quando o app não mostra mais o anúncio ou não interage mais com ele. Para anúncios com escopo de tela, remova a referência quando o app remover a tela host da memória. Para anúncios com escopo de app, mantenha a referência do anúncio enquanto o usuário navega pelas telas e descarte-a 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 de apresentação para 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 host, o 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 uma variável de instância de tela única.

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