Wdrażanie reklam typu obraz w obrazie (beta)

Obraz w obrazie

Reklamy obraz w obrazie (PiP) wyświetlają się w pływającym oknie, które pozostaje na wierzchu treści na ekranie, takich jak artykuły, kanały czy rozgrywka. Ten format umożliwia użytkownikom interakcję z Twoją aplikacją, gdy reklama jest widoczna. Jeśli chcesz wyświetlać reklamy, które nie zajmują całego ekranu, wybierz ten format. Więcej informacji o reklamach obraz w obrazie ads.

Z tego przewodnika dowiesz się, jak żądać i wyświetlać reklamy obraz w obrazie w aplikacji za pomocą GMA Next-Gen SDK.

Zanim zaczniesz

Zanim przejdziesz dalej, wykonaj te czynności:

Wczytywanie reklamy

Aby wczytać a PictureInPictureAd, utwórz żądanie reklamy i wywołaj metodę 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);
        }
      });
}

Zastąp AD_UNIT_ID identyfikatorem jednostki reklamowej.

Wyświetlanie reklamy

Aby wyświetlić reklamę obraz w obrazie na ekranie, skonfiguruj opcje obrazu w obrazie i wywołaj metodę show. W tym przykładzie ustawiamy domyślną pozycję reklamy i zakres prezentacji na ekran:

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

Ustawianie pozycji

Domyślnie GMA Next-Gen SDK wyświetla reklamę obraz w obrazie w prawym dolnym rogu ekranu, gdy jest ona wyświetlana po raz pierwszy, lub w ostatniej znanej pozycji, jeśli była już wyświetlana. Aby dostosować miejsce wyświetlania reklamy, ustaw pozycję w opcjach obrazu w obrazie. W tym przykładzie ustawiamy pozycję na wierzchu treści w lewym górnym rogu ekranu:

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

Wszystkie dostępne pozycje znajdziesz w PictureInPictureAdPosition.

Ustawianie zakresu prezentacji

Domyślnie GMA Next-Gen SDK wiąże reklamę obraz w obrazie z bieżącym ekranem hosta. GMA Next-Gen SDK odrzuca reklamę, gdy hierarchia widoków ekranu hosta nie jest już w pamięci. Aby reklama była widoczna po usunięciu ekranu hosta z pamięci, ustaw zakres prezentacji na aplikację:

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

Więcej informacji znajdziesz w artykule Zachowywanie widoczności reklamy na różnych ekranach.

Ustawianie wywołania zwrotnego zdarzenia reklamy

Aby obsługiwać zdarzenia cyklu życia reklamy obraz w obrazie, przed jej wyświetleniem ustaw wywołanie zwrotne zdarzenia w reklamie. To wywołanie zwrotne zgłasza standardowe zdarzenia, takie jak kliknięcia i wyświetlenia. Zgłasza też zdarzenia specyficzne dla obrazu w obrazie, np. gdy reklama jest wyświetlana lub ukryta:

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

Ukrywanie reklamy

Aby usunąć pływającą reklamę z ekranu, wywołaj metodę hide. Ta metoda wywołuje wywołanie zwrotne zdarzenia ukrycia reklamy:

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

Zwalnianie miejsca zajmowanego przez zasoby reklamowe

Aby uniknąć wycieków pamięci, usuń odwołanie do obiektu reklamy, gdy aplikacja przestanie go używać. Na przykład gdy aplikacja nie będzie już wyświetlać reklamy ani wchodzić z nią w interakcję. W przypadku reklam w zakresie ekranu usuń odwołanie, gdy aplikacja usunie ekran hosta z pamięci. W przypadku reklam w zakresie aplikacji zachowaj odwołanie do reklamy, gdy użytkownik przechodzi między ekranami, i usuń odwołanie, gdy użytkownik zamknie reklamę:

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

Zachowywanie widoczności reklamy na różnych ekranach

Gdy ustawisz zakres prezentacji na aplikację, reklama obraz w obrazie pozostanie widoczna nawet wtedy, gdy aplikacja usunie ekran hosta z pamięci. Aby wchodzić w interakcję z reklamą lub ją zamykać, gdy użytkownik opuści ekran hosta, aplikacja musi zachować dostęp do reklamy obraz w obrazie. Zalecamy przechowywanie reklamy w singletonie na poziomie aplikacji lub w menedżerze stanu współdzielonego, a nie w zmiennej instancji pojedynczego ekranu.

Przykłady zachowywania widoczności reklamy na różnych ekranach znajdziesz w naszych przykładowych aplikacjach: