Implementeer beeld-in-beeld-advertenties (beta)

Beeld-in-beeld

Picture-in-picture (PiP) advertenties worden weergegeven in een zwevend venster dat boven de content op het scherm blijft staan, zoals artikelen, feeds of gameplay. Met dit formaat kunnen gebruikers interactie hebben met uw app terwijl de advertentie zichtbaar blijft. Kies dit formaat om advertenties weer te geven die niet het hele scherm in beslag nemen. Lees meer over picture-in-picture advertenties .

Deze handleiding beschrijft hoe u picture-in-picture-advertenties in uw app kunt aanvragen en weergeven met behulp van GMA Next-Gen SDK .

Voordat je begint

Voordat u verdergaat, dient u het volgende te doen:

Een advertentie laden

Om een PictureInPictureAd te laden, maakt u een advertentieverzoek aan en roept u de load methode aan:

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

Vervang AD_UNIT_ID door uw advertentie-eenheid-ID.

Toon de advertentie

Om de picture-in-picture-advertentie op het scherm weer te geven, configureert u de picture-in-picture-opties en roept u de show methode aan. Het volgende voorbeeld stelt de standaardpositie van de advertentie en het weergavebereik in op het scherm:

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

Stel de positie in

Standaard toont GMA Next-Gen SDK een picture-in-picture-advertentie in de rechterbenedenhoek van het scherm wanneer deze voor het eerst wordt weergegeven, of op de laatst bekende positie als deze eerder is weergegeven. Om de positie van de advertentie aan te passen, kunt u de positie instellen in uw picture-in-picture-opties. Het volgende voorbeeld plaatst de advertentie boven de inhoud in de linkerbovenhoek van het scherm:

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

Voor alle beschikbare vacatures, zie PictureInPictureAdPosition .

Bepaal het presentatiebereik

Standaard koppelt GMA Next-Gen SDK een picture-in-picture-advertentie aan het huidige hostscherm. GMA Next-Gen SDK sluit de advertentie wanneer de weergavehiërarchie van het hostscherm niet langer in het geheugen aanwezig is. Om de advertentie zichtbaar te houden nadat het hostscherm uit het geheugen is verwijderd, stelt u het presentatiebereik in op de applicatie.

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

Zie voor meer informatie: De advertentie op alle schermen zichtbaar houden .

Stel de callback-functie voor advertentie-evenementen in.

Om gebeurtenissen in de levenscyclus van picture-in-picture-advertenties af te handelen, stelt u de gebeurteniscallback in voor uw advertentie voordat u deze weergeeft. Deze callback rapporteert standaardgebeurtenissen, zoals klikken en vertoningen. Deze callback rapporteert ook picture-in-picture-specifieke gebeurtenissen, zoals wanneer de advertentie wordt weergegeven of verborgen.

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

Verberg de advertentie

Om de zwevende advertentie van het scherm te verwijderen, roept u de hide -methode aan. Deze methode roept de `ad hidden`-gebeurteniscallback aan:

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

Advertentiebronnen opruimen

Om geheugenlekken te voorkomen, moet u de verwijzing naar het advertentieobject verwijderen zodra uw app de advertentie niet meer gebruikt. Bijvoorbeeld wanneer uw app de advertentie niet meer weergeeft of er niet meer mee interacteert. Voor schermgebonden advertenties verwijdert u de verwijzing wanneer uw app het hostscherm uit het geheugen verwijdert. Voor app-gebonden advertenties behoudt u de verwijzing naar de advertentie terwijl de gebruiker tussen schermen navigeert en verwijdert u de verwijzing wanneer de gebruiker de advertentie sluit.

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

Zorg ervoor dat de advertentie op alle schermen zichtbaar blijft.

Wanneer u het presentatiebereik instelt op de applicatie, blijft de picture-in-picture-advertentie zichtbaar, zelfs wanneer uw app het hostscherm uit het geheugen verwijdert. Om met de advertentie te kunnen interageren of deze te sluiten wanneer de gebruiker het hostscherm verlaat, moet uw app toegang tot de picture-in-picture-advertentie behouden. We raden aan de advertentie op te slaan in een singleton op app-niveau of in een gedeelde statusmanager in plaats van in een instantievariabele van een enkel scherm.

Bekijk onze voorbeeld-apps voor een voorbeeld van hoe u een advertentie op verschillende schermen zichtbaar kunt houden: