Implémenter les annonces Picture-in-picture (bêta)

Sélectionnez une plate-forme : Android iOS Unity

Picture-in-picture

Les annonces Picture-in-Picture (PiP) s'affichent dans une fenêtre flottante qui reste au-dessus du contenu de l'écran, comme des articles, des flux ou des jeux. Ce format permet aux utilisateurs d'interagir avec votre application tout en laissant l'annonce visible. Choisissez ce format pour diffuser des annonces qui n'occupent pas tout l'écran. En savoir plus sur les annonces Picture-in-Picture.

Ce guide explique comment demander et diffuser des annonces Picture-in-Picture dans votre application à l'aide de Google Mobile Ads SDK.

Avant de commencer

Avant de continuer, procédez comme suit :

Charger une annonce

Pour charger un GADPictureInPictureAd objet, créez une demande d'annonce et appelez la méthode de chargement :

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)")
  }
}

Remplacez adUnitID par l'ID de votre bloc d'annonces.

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;
      }];
}

Remplacez kAdUnitID par l'ID de votre bloc d'annonces.

Diffuser l'annonce

Pour afficher l'annonce Picture-in-Picture à l'écran, appelez la méthode show. L'exemple suivant affiche l'annonce dans la position par défaut et définit le champ d'application de la présentation sur l'écran :

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];
}

Définir la position

Par défaut, Google Mobile Ads SDK affiche une annonce Picture-in-Picture en bas à droite de l'écran lors de sa première diffusion, ou à la dernière position connue si elle a déjà été diffusée. Pour personnaliser l'emplacement de l'annonce, spécifiez une position lors de sa diffusion. L'exemple suivant définit la position au-dessus du contenu, en haut à gauche de l'écran :

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;
}

Pour connaître toutes les positions disponibles, consultez GADPictureInPictureAdPosition.

Définir le champ d'application de la présentation

Par défaut, Google Mobile Ads SDK lie une annonce Picture-in-Picture à l'écran hôte actuel. Google Mobile Ads SDK ignore l'annonce lorsque la hiérarchie des vues de l'écran hôte n'est plus en mémoire. Pour que l'annonce reste visible après la suppression de l'écran hôte de la mémoire, définissez le champ d'application de la présentation sur l'application :

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;
}

Pour en savoir plus, consultez Conserver l'annonce visible sur plusieurs écrans.

Écouter les événements d'annonce

Pour gérer les événements de cycle de vie des annonces Picture-in-Picture, enregistrez-vous aux événements d'annonce avant de diffuser votre annonce. Ces événements signalent les interactions avec les annonces, telles que les clics et les impressions. Ils signalent également les événements spécifiques aux annonces Picture-in-Picture, par exemple lorsque l'annonce s'affiche ou est masquée :

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.");
}

Masquer l'annonce

Pour supprimer l'annonce flottante de l'écran, appelez la méthode hide. Cette méthode appelle l'événement d'annonce masquée :

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];
}

Nettoyer les ressources d'annonce

Pour éviter les fuites de mémoire, supprimez votre référence à l'objet d'annonce lorsque votre application a fini d'utiliser l'annonce. Par exemple, lorsque votre application n'affiche plus l'annonce ou n'interagit plus avec elle. Pour les annonces dont le champ d'application est l'écran, supprimez la référence lorsque votre application supprime l'écran hôte de la mémoire. Pour les annonces dont le champ d'application est l'application, conservez la référence à l'annonce pendant que l'utilisateur navigue entre les écrans, et supprimez-la lorsque l'utilisateur ignore l'annonce :

Swift

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

Objective-C

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

Conserver l'annonce visible sur plusieurs écrans

Lorsque vous définissez le champ d'application de la présentation sur l'application, l'annonce Picture-in-Picture reste visible même lorsque votre application supprime l'écran d'hébergement de la mémoire. Pour interagir avec l'annonce ou l'ignorer lorsque l'utilisateur quitte l'écran hôte, votre application doit conserver l'accès à l'annonce Picture-in-Picture. Nous vous recommandons de conserver l'annonce dans un singleton au niveau de l'application ou dans un gestionnaire d'état partagé plutôt que dans la variable d'instance d'un seul écran.

Pour obtenir des exemples sur la façon de conserver une annonce visible sur plusieurs écrans, consultez les exemples d'applications suivants :