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

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 pendant que l'annonce reste visible. Pour diffuser des annonces qui n'occupent pas tout l'écran, choisissez ce format. 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 GMA Next-Gen SDK.

Avant de commencer

Avant de continuer, procédez comme suit :

Charger une annonce

Pour charger un PictureInPictureAd, créez une demande d'annonce et appelez la méthode load :

Kotlin

private fun loadPictureInPictureAd() {
  val request = PictureInPictureAdRequest.Builder(AD_UNIT_ID).build()

  PictureInPictureAd.load(
    request,
    object : AdLoadCallback<PictureInPictureAd> {
      override fun onAdFailedToLoad(adError: LoadAdError) {
        Log.w(TAG, "Picture-in-Picture ad failed to load: $adError")
      }

      override fun onAdLoaded(ad: PictureInPictureAd) {
        Log.d(TAG, "Picture-in-Picture ad loaded.")

        // Capture the PictureInPictureAd reference for later use.
        pipAd = ad
        setAdEventCallback(ad)
      }
    },
  )
}

Java

private void loadPictureInPictureAd() {
  PictureInPictureAdRequest request = new PictureInPictureAdRequest.Builder(AD_UNIT_ID).build();

  PictureInPictureAd.load(
      request,
      new AdLoadCallback<PictureInPictureAd>() {
        @Override
        public void onAdFailedToLoad(@NonNull LoadAdError adError) {
          Log.w(TAG, "Picture-in-Picture ad failed to load: " + adError);
        }

        @Override
        public void onAdLoaded(@NonNull PictureInPictureAd ad) {
          Log.d(TAG, "Picture-in-Picture ad loaded.");

          // Capture the PictureInPictureAd reference for later use.
          pipAd = ad;
          setAdEventCallback(ad);
        }
      });
}

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

Diffuser l'annonce

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

Kotlin

private fun showPictureInPictureAd(activity: Activity) {
  // Capture the ad reference saved from the onAdLoaded callback.
  val ad = pipAd
  if (ad != null) {
    val options =
      PictureInPictureAdOptions.Builder()
        // Uses the Google Mobile Ads SDK's default screen position.
        .setPosition(PictureInPictureAdPosition.DEFAULT)
        // Binds the ad lifecycle to the host screen.
        .setPresentationScope(PictureInPictureAdPresentationScope.SCREEN)
        .build()
    ad.show(activity, options)
  } else {
    Log.d(TAG, "No ad to show.")
  }
}

Java

private void showPictureInPictureAd(@NonNull Activity activity) {
  // Use the ad reference saved from the onAdLoaded callback.
  if (pipAd != null) {
    PictureInPictureAdOptions options =
        new PictureInPictureAdOptions.Builder()
            // Uses the Google Mobile Ads SDK's default screen position.
            .setPosition(PictureInPictureAdPosition.DEFAULT)
            // Binds the ad lifecycle to the host screen.
            .setPresentationScope(PictureInPictureAdPresentationScope.SCREEN)
            .build();
    pipAd.show(activity, options);
  } else {
    Log.d(TAG, "No ad to show.");
  }
}

Définir la position

Par défaut, GMA Next-Gen 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, définissez la position dans vos options Picture-in-Picture. L'exemple suivant définit la position au-dessus du contenu, en haut à gauche de l'écran :

Kotlin

private fun createTopLeftPositionOptions(): PictureInPictureAdOptions {
  return PictureInPictureAdOptions.Builder()
    // Sets the ad position to the top-left corner of the screen.
    .setPosition(PictureInPictureAdPosition.TOP_LEFT)
    .build()
}

Java

private PictureInPictureAdOptions createTopLeftPositionOptions() {
  return new PictureInPictureAdOptions.Builder()
      // Sets the ad position to the top-left corner of the screen.
      .setPosition(PictureInPictureAdPosition.TOP_LEFT)
      .build();
}

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

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

Par défaut, GMA Next-Gen SDK lie une annonce Picture-in-Picture à l'écran hôte actuel. GMA Next-Gen 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 :

Kotlin

private fun createApplicationScopedOptions(): PictureInPictureAdOptions {
  return PictureInPictureAdOptions.Builder()
    // Keeps the ad visible beyond the host screen's lifecycle.
    .setPresentationScope(PictureInPictureAdPresentationScope.APPLICATION)
    .build()
}

Java

private PictureInPictureAdOptions createApplicationScopedOptions() {
  return new PictureInPictureAdOptions.Builder()
      // Keeps the ad visible beyond the host screen's lifecycle.
      .setPresentationScope(PictureInPictureAdPresentationScope.APPLICATION)
      .build();
}

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

Définir le rappel d'événement d'annonce

Pour gérer les événements de cycle de vie des annonces Picture-in-Picture, définissez le rappel d'événement sur votre annonce avant de la diffuser. Ce rappel signale les événements standards, tels que les clics et les impressions. Il signale également les événements spécifiques aux annonces Picture-in-Picture, par exemple lorsque l'annonce est affichée ou masquée :

Kotlin

private fun setAdEventCallback(pipAd: PictureInPictureAd) {
  pipAd.adEventCallback =
    object : PictureInPictureAdEventCallback {
      override fun onAdShown() {
        Log.d(TAG, "Picture-in-Picture ad shown.")
      }

      override fun onAdHidden() {
        Log.d(TAG, "Picture-in-Picture ad hidden.")
      }

      override fun onAdImpression() {
        Log.d(TAG, "Picture-in-Picture ad recorded an impression.")
      }

      override fun onAdClicked() {
        Log.d(TAG, "Picture-in-Picture ad recorded a click.")
      }

      override fun onAdShowedFullScreenContent() {
        Log.d(TAG, "Picture-in-Picture ad showed full screen content.")
      }

      override fun onAdDismissedFullScreenContent() {
        Log.d(TAG, "Picture-in-Picture ad dismissed full screen content.")
      }

      override fun onAdFailedToShowFullScreenContent(
        fullScreenContentError: FullScreenContentError
      ) {
        Log.w(
          TAG,
          "Picture-in-Picture ad failed to show full screen content: $fullScreenContentError",
        )
      }

      override fun onAdPaid(value: AdValue) {
        Log.d(TAG, "Picture-in-Picture ad paid: ${value.valueMicros} ${value.currencyCode}")
      }
    }
}

Java

private void setAdEventCallback(@NonNull PictureInPictureAd pipAd) {
  pipAd.setAdEventCallback(
      new PictureInPictureAdEventCallback() {
        @Override
        public void onAdShown() {
          Log.d(TAG, "Picture-in-Picture ad shown.");
        }

        @Override
        public void onAdHidden() {
          Log.d(TAG, "Picture-in-Picture ad hidden.");
        }

        @Override
        public void onAdImpression() {
          Log.d(TAG, "Picture-in-Picture ad recorded an impression.");
        }

        @Override
        public void onAdClicked() {
          Log.d(TAG, "Picture-in-Picture ad recorded a click.");
        }

        @Override
        public void onAdShowedFullScreenContent() {
          Log.d(TAG, "Picture-in-Picture ad showed full screen content.");
        }

        @Override
        public void onAdDismissedFullScreenContent() {
          Log.d(TAG, "Picture-in-Picture ad dismissed full screen content.");
        }

        @Override
        public void onAdFailedToShowFullScreenContent(
            @NonNull FullScreenContentError fullScreenContentError) {
          Log.w(
              TAG,
              "Picture-in-Picture ad failed to show full screen content: "
                  + fullScreenContentError);
        }

        @Override
        public void onAdPaid(@NonNull AdValue value) {
          Log.d(
              TAG,
              "Picture-in-Picture ad paid: "
                  + value.getValueMicros()
                  + " "
                  + value.getCurrencyCode());
        }
      });
}

Masquer l'annonce

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

Kotlin

private fun hidePictureInPictureAd() {
  // Capture the ad reference saved from the onAdLoaded callback.
  val ad = pipAd
  if (ad != null) {
    ad.hide()
  } else {
    Log.d(TAG, "No ad to hide.")
  }
}

Java

private void hidePictureInPictureAd() {
  // Use the ad reference saved from the onAdLoaded callback.
  if (pipAd != null) {
    pipAd.hide();
  } else {
    Log.d(TAG, "No ad to 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 :

Kotlin

private fun cleanUpPictureInPictureAd() {
  pipAd?.destroy()
  pipAd = null
}

Java

private void cleanUpPictureInPictureAd() {
  // Use the ad reference saved from the onAdLoaded callback.
  if (pipAd != null) {
    pipAd.destroy();
    pipAd = null;
  }
}

Maintenir 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 hôte 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 une variable d'instance d'un seul écran.

Pour obtenir un exemple de la façon de maintenir une annonce visible sur plusieurs écrans, consultez nos exemples d'applications :