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 permanece visível. Para mostrar anúncios que não ocupam a tela inteira, escolha esse formato. Saiba mais sobre os anúncios picture-in-picture.

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 loadPictureInPictureAd() async {
  do {
    // Capture the PictureInPictureAd reference for later use.
    pipAd = try await PictureInPictureAd.load(
      with: adUnitID, request: Request())
    // 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)loadPictureInPictureAd {
  GADRequest *request = [GADRequest 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 opções de picture-in-picture 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.