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 à l'écran, comme des articles, des flux ou du gameplay. Ce format permet aux utilisateurs d'interagir avec votre application pendant que l'annonce reste visible. Choisissez ce format pour diffuser des annonces qui n'occupent pas tout l'écran.

Ce guide explique comment demander et afficher 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 objet GADPictureInPictureAd, créez une demande d'annonce et appelez la méthode de chargement :

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

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

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

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 à 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 l'affichage de l'annonce. L'exemple suivant définit la position au-dessus du contenu, dans l'angle supérieur 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 tous les postes disponibles, consultez GADPictureInPictureAdPosition.

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

Par défaut, Google Mobile Ads SDK associe une annonce Picture-in-picture à l'écran hôte actuel. Google Mobile Ads SDK ferme 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 la visibilité de l'annonce sur tous les écrans.

Écouter les événements d'annonce

Pour gérer les événements de cycle de vie des annonces Picture-in-picture, enregistrez-vous pour recevoir les é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. Ces événements signalent également des événements spécifiques au mode 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 publicitaires

Pour éviter les fuites de mémoire, supprimez la 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 limitées à l'écran, supprimez la référence lorsque votre application supprime l'écran hôte de la mémoire. Pour les annonces au niveau de l'application, conservez la référence de l'annonce pendant que l'utilisateur parcourt les écrans, puis supprimez-la lorsqu'il ferme l'annonce :

Swift

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

Objective-C

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

Maintenir l'annonce visible sur tous les é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 la fermer 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 une variable d'instance d'un seul écran.

Pour savoir comment maintenir une annonce visible sur plusieurs écrans, consultez les exemples d'applications suivants :