Konfigurowanie reklam pełnoekranowych z nagrodą

Pakiet SDK nowej generacji.

Wybierz platformę: Android iOS Unity Flutter Android (starsza wersja)

Reklamy pełnoekranowe z nagrodą to format, który umożliwia oferowanie nagród za reklamy wyświetlane automatycznie w naturalnych momentach przejściowych w aplikacji. W przeciwieństwie do reklam z nagrodą użytkownicy nie muszą wyrazić zgody na wyświetlenie reklamy pełnoekranowej z nagrodą. Więcej informacji znajdziesz w przewodniku po reklamach pełnoekranowych z nagrodą.

Z tego przewodnika dowiesz się, jak zintegrować reklamy pełnoekranowe z nagrodą z aplikacją na Androida.

Zanim zaczniesz

Zanim przejdziesz dalej, wykonaj te czynności:

  • Skonfiguruj GMA Next-Gen SDK.
  • Użyj identyfikatora testowej jednostki reklamowej z nagrodą ca-app-pub-3940256099942544/5354046379.
    • Podczas tworzenia i testowania aplikacji używaj reklam testowych, a nie reklam rzeczywistych. Jeśli tego nie zrobisz, możemy zawiesić Twoje konto.
    • Zanim opublikujesz aplikację, zastąp ten identyfikator identyfikatorem jednostki reklamowej.
    • Więcej informacji o reklamach testowych GMA Next-Gen SDK znajdziesz w artykule Włączanie reklam testowych.

Informacje o wstępnym ładowaniu reklam

Wstępne ładowanie reklam w GMA Next-Gen SDK automatyzuje ładowanie i buforowanie reklam.

Wstępne wczytywanie reklam zapewnia te korzyści:

  • Zarządzanie odwołaniami: odwołania są utrzymywane do momentu wyświetlenia reklam.
  • Automatyczne ponowne wczytywanie: gdy reklama zostanie pobrana z pamięci podręcznej, wczytuje się nowa.
  • Zarządzane ponawianie: gdy nie uda się wczytać reklamy, wczytuje się nowa.
  • Obsługa wygasania: reklamy są odświeżane przed wygaśnięciem.
  • Optymalizacja pamięci podręcznej: kolejność w pamięci podręcznej jest optymalizowana, aby wyświetlać reklamy o najwyższym priorytecie.

Rozpoczynanie wstępnego ładowania reklam

Aby rozpocząć wstępne wczytywanie reklam, wywołaj metodę startPreload() raz na początku działania aplikacji. Po wywołaniu metody startPreload() GMA Next-Gen SDK automatycznie wstępnie wczytuje reklamy i ponawia nieudane żądania dotyczące wstępnie wczytanych konfiguracji.

Ten przykład pokazuje, jak rozpocząć wstępne wczytywanie reklam:

Kotlin

// Call start() once after SDK initialization.
// Preload only one ad unit per format to optimize performance.
val adRequest = AdRequest.Builder(adUnitId).build()
val preloadConfig = PreloadConfiguration(adRequest)
RewardedInterstitialAdPreloader.start(adUnitId, preloadConfig)

Java

// Call start() once after SDK initialization.
// Preload only one ad unit per format to optimize performance.
AdRequest adRequest = new AdRequest.Builder(adUnitId).build();
PreloadConfiguration preloadConfig = new PreloadConfiguration(adRequest);
RewardedInterstitialAdPreloader.start(adUnitId, preloadConfig);

Zastąp AD_UNIT_ID identyfikatorem jednostki reklamowej.

W poprzednim przykładzie pokazaliśmy, jak używać identyfikatora jednostki reklamowej jako identyfikatora wstępnego wczytywania. Identyfikator wstępnego ładowania reklam to ciąg znaków, który tworzysz w celu identyfikacji konfiguracji wstępnego ładowania reklam. Jeśli Twoja aplikacja wymaga wielu konfiguracji kierowania na ten sam identyfikator jednostki reklamowej, przekaż niestandardowy identyfikator w postaci ciągu znaków.

Pobieranie i wyświetlanie wstępnie wczytanej reklamy

Gdy chcesz wyświetlić reklamę, wywołaj metodę pollAd(). GMA Next-Gen SDK pobiera dostępną reklamę i automatycznie wstępnie wczytuje następną reklamę w tle. Jeśli żadna reklama nie jest dostępna, GMA Next-Gen SDK nie zwraca żadnych reklam.

Gdy masz dostępny obiekt reklamy, wywołaj metodę show, aby wyświetlić reklamę. Użyj detektora nagród, aby obsługiwać zdarzenia związane z nagrodami. Ten przykład pokazuje, jak pobrać i wyświetlić wstępnie wczytaną reklamę:

Kotlin

private fun pollAndShowAd(activity: Activity, adUnitId: String) {
  // Polling returns the next available ad and loads another ad in the background.
  val ad = RewardedInterstitialAdPreloader.pollAd(adUnitId)
  if (ad == null) {
    Log.e(TAG, "Rewarded interstitial ad is not available.")
    return
  }

  // Interact with the ad object as needed.
  Log.d(TAG, "Rewarded interstitial ad response info: ${ad.getResponseInfo()}")
  ad.adEventCallback =
    object : RewardedInterstitialAdEventCallback {
      override fun onAdImpression() {
        Log.d(TAG, "Rewarded interstitial ad recorded an impression.")
      }
    }
  ad.show(activity) { rewardItem -> Log.d(TAG, "User earned reward: ${rewardItem.amount}") }
}

Java

private void pollAndShowAd(Activity activity, String adUnitId) {
  // Polling returns the next available ad and loads another ad in the background.
  final RewardedInterstitialAd ad = RewardedInterstitialAdPreloader.pollAd(adUnitId);

  // Interact with the ad object as needed.
  if (ad == null) {
    Log.e(TAG, "Rewarded interstitial ad is not available.");
    return;
  }

  Log.d(TAG, "Rewarded interstitial ad response info: " + ad.getResponseInfo());
  ad.setAdEventCallback(
      new RewardedInterstitialAdEventCallback() {
        @Override
        public void onAdImpression() {
          Log.d(TAG, "Rewarded interstitial ad recorded an impression.");
        }
      });

  // Show the ad.
  ad.show(
      activity,
      rewardItem -> {
        Log.d(TAG, "User earned reward: " + rewardItem.getAmount());
      });
}

Nie wywołuj metody pollAd() , dopóki nie będziesz gotowy(-a) do wyświetlenia reklamy. Aby odczytać informacje o odpowiedzi na reklamę bez jej wyświetlania, zapoznaj się z sekcją Odczytywanie informacji o odpowiedzi.

Nasłuchiwanie zdarzeń związanych z reklamami

Zanim wyświetlisz reklamę, nasłuchuj zdarzeń związanych z reklamami. Ten przykład pokazuje, jak zarejestrować wywołania zwrotne dla zdarzeń związanych z reklamami:

Kotlin

private fun listenToAdEvents() {
  // Listen for ad events.
  val ad = rewardedInterstitialAd
  if (ad == null) {
    Log.e(TAG, "Rewarded interstitial ad is not ready yet.")
    return
  }

  ad.adEventCallback =
    object : RewardedInterstitialAdEventCallback {
      override fun onAdShowedFullScreenContent() {
        // Rewarded interstitial ad did show.
      }

      override fun onAdDismissedFullScreenContent() {
        // Rewarded interstitial ad did dismiss.
        rewardedInterstitialAd = null
      }

      override fun onAdFailedToShowFullScreenContent(
        fullScreenContentError: FullScreenContentError
      ) {
        // Rewarded interstitial ad failed to show.
        Log.e(TAG, "Rewarded interstitial ad failed to show: ${fullScreenContentError.message}")
      }

      override fun onAdImpression() {
        // Rewarded interstitial ad did record an impression.
      }

      override fun onAdClicked() {
        // Rewarded interstitial ad did record a click.
      }
    }
}

Java

private void listenToAdEvents() {
  // Listen for ad events.
  if (rewardedInterstitialAd == null) {
    Log.e(TAG, "Rewarded interstitial ad is not ready yet.");
    return;
  }

  rewardedInterstitialAd.setAdEventCallback(
      new RewardedInterstitialAdEventCallback() {
        @Override
        public void onAdShowedFullScreenContent() {
          // Rewarded interstitial ad did show.
        }

        @Override
        public void onAdDismissedFullScreenContent() {
          // Rewarded interstitial ad did dismiss.
          rewardedInterstitialAd = null;
        }

        @Override
        public void onAdFailedToShowFullScreenContent(
            @NonNull FullScreenContentError fullScreenContentError) {
          // Rewarded interstitial ad failed to show.
          Log.e(
              TAG,
              "Rewarded interstitial ad failed to show: " + fullScreenContentError.getMessage());
        }

        @Override
        public void onAdImpression() {
          // Rewarded interstitial ad did record an impression.
        }

        @Override
        public void onAdClicked() {
          // Rewarded interstitial ad did record a click.
        }
      });
}

Opcjonalnie: weryfikowanie wywołań zwrotnych weryfikacji po stronie serwera

Jeśli Twoja aplikacja wymaga dodatkowych danych w wywołaniach zwrotnych weryfikacji po stronie serwera, użyj funkcji danych niestandardowych w reklamach pełnoekranowych z nagrodą. Każda wartość ciągu znaków ustawiona w obiekcie reklamy pełnoekranowej z nagrodą jest przekazywana do parametru zapytania custom_data wywołania zwrotnego weryfikacji po stronie serwera. Jeśli nie ustawisz wartości danych niestandardowych, wartość parametru zapytania custom_data nie będzie obecna w wywołaniu zwrotnym weryfikacji po stronie serwera.

Ten przykładowy kod pokazuje, jak ustawić dane niestandardowe w obiekcie reklamy pełnoekranowej z nagrodą przed wyświetleniem reklamy:

Kotlin

RewardedInterstitialAd.load(
  context,
  AD_UNIT_ID,
  AdRequest.Builder().build(),
  object : RewardedInterstitialAdLoadCallback() {
    override fun onAdLoaded(ad: RewardedInterstitialAd) {
      rewardedInterstitialAd = ad
      val options =
        ServerSideVerificationOptions.Builder().setCustomData("SAMPLE_CUSTOM_DATA_STRING").build()
      rewardedInterstitialAd?.setServerSideVerificationOptions(options)
    }
  },
)

Java

RewardedInterstitialAd.load(
    context,
    AD_UNIT_ID,
    new AdRequest.Builder().build(),
    new RewardedInterstitialAdLoadCallback() {
      @Override
      public void onAdLoaded(RewardedInterstitialAd ad) {
        rewardedInterstitialAd = ad;
        ServerSideVerificationOptions options =
            new ServerSideVerificationOptions.Builder()
                .setCustomData("SAMPLE_CUSTOM_DATA_STRING")
                .build();
        rewardedInterstitialAd.setServerSideVerificationOptions(options);
      }
    });

Zastąp SAMPLE_CUSTOM_DATA_STRING swoimi danymi niestandardowymi.

Opcjonalnie: nasłuchiwanie zdarzeń wstępnego wczytywania

Gdy rozpoczniesz wstępne wczytywanie reklam, zarejestruj się, aby otrzymywać powiadomienia o zdarzeniach wstępnego wczytywania, gdy reklamy zostaną wstępnie wczytane, nie uda się ich wstępnie wczytać lub gdy wyczerpie się pamięć podręczna reklam.

Ten przykład pokazuje, jak zarejestrować się, aby otrzymywać powiadomienia o zdarzeniach wstępnego wczytywania reklam:

Kotlin

val preloadCallback =
  // [Important] Don't call ad preloader start() or pollAd() within the PreloadCallback.
  object : PreloadCallback {
    override fun onAdFailedToPreload(preloadId: String, adError: LoadAdError) {
      Log.d(
        TAG,
        "Rewarded interstitial preload ad $preloadId failed to load with error: ${adError.message}",
      )
    }

    override fun onAdsExhausted(preloadId: String) {
      Log.i(TAG, "Rewarded interstitial preload ad $preloadId is not available")
      // [Important] Don't call ad preloader start() or pollAd() from onAdsExhausted.
    }

    override fun onAdPreloaded(preloadId: String, responseInfo: ResponseInfo) {
      Log.i(TAG, "Rewarded interstitial preload ad $preloadId is available")
    }
  }
val adRequest = AdRequest.Builder(adUnitId).build()
val preloadConfig = PreloadConfiguration(adRequest)
RewardedInterstitialAdPreloader.start(adUnitId, preloadConfig, preloadCallback)

Java

PreloadCallback preloadCallback =
    // [Important] Don't call ad preloader start() or pollAd() within the PreloadCallback.
    new PreloadCallback() {
      @Override
      public void onAdFailedToPreload(@NonNull String preloadId, @NonNull LoadAdError adError) {
        Log.d(
            TAG,
            String.format(
                "Rewarded interstitial preload ad %s failed to load with error: %s",
                preloadId, adError.getMessage()));
        // [Optional] Get the error response info for additional details.
        // ResponseInfo responseInfo = adError.getResponseInfo();
      }

      @Override
      public void onAdsExhausted(@NonNull String preloadId) {
        Log.i(TAG, "Rewarded interstitial preload ad " + preloadId + " is not available");
        // [Important] Don't call ad preloader start() or pollAd() from onAdsExhausted.
      }

      @Override
      public void onAdPreloaded(@NonNull String preloadId, @NonNull ResponseInfo responseInfo) {
        Log.i(TAG, "Rewarded interstitial preload ad " + preloadId + " is available");
      }
    };
AdRequest adRequest = new AdRequest.Builder(adUnitId).build();
PreloadConfiguration preloadConfig = new PreloadConfiguration(adRequest);
RewardedInterstitialAdPreloader.start(adUnitId, preloadConfig, preloadCallback);

Gdy nie uda się wczytać reklamy, GMA Next-Gen SDK automatycznie wstępnie wczytuje reklamy i ponawia nieudane żądania dotyczące wstępnie wczytanych konfiguracji.

Opcjonalnie: sprawdzanie dostępności reklam

Jeśli chcesz sprawdzić, czy reklama jest dostępna, sprawdź jej dostępność. Ten przykład pokazuje, jak sprawdzić, czy wstępnie wczytana reklama jest dostępna:

Kotlin

private fun isAdAvailable(adUnitId: String): Boolean {
  return RewardedInterstitialAdPreloader.isAdAvailable(adUnitId)
}

Java

private boolean isAdAvailable(String adUnitId) {
  return RewardedInterstitialAdPreloader.isAdAvailable(adUnitId);
}

Opcjonalnie: ustawianie rozmiaru bufora

Rozmiar bufora określa liczbę wstępnie wczytanych reklam przechowywanych w pamięci. Domyślnie Google optymalizuje rozmiar bufora, aby zrównoważyć zużycie pamięci i opóźnienie wyświetlania reklam. Możesz ustawić niestandardowy rozmiar bufora, aby zwiększyć liczbę reklam przechowywanych w pamięci. Zalecamy maksymalny rozmiar bufora wynoszący 4.

Ten przykład pokazuje, jak ustawić rozmiar bufora na 4 wstępnie wczytane reklamy:

Kotlin

val adRequest = AdRequest.Builder(adUnitId).build()
// Maintain small or default buffer size unless rapid transitions are expected.
val preloadConfig = PreloadConfiguration(adRequest, bufferSize = 4)
RewardedInterstitialAdPreloader.start(adUnitId, preloadConfig)

Java

// Maintain small or default buffer size unless rapid transitions are expected.
AdRequest adRequest = new AdRequest.Builder(adUnitId).build();
PreloadConfiguration preloadConfig = new PreloadConfiguration(adRequest, 4);
RewardedInterstitialAdPreloader.start(adUnitId, preloadConfig);

Limity pamięci podręcznej wstępnego wczytywania

GMA Next-Gen SDK wymusza limit całkowitej liczby wstępnie wczytanych reklam w całej aplikacji we wszystkich jednostkach reklamowych i identyfikatorach wstępnego wczytywania:

  • Domyślny limit: Google przechowuje w pamięci maksymalnie 6 wstępnie wczytanych reklam. Ten limit jest wspólny dla wszystkich formatów i identyfikatorów wstępnego wczytywania.
  • Zalecamy, aby rozmiar bufora wynosił 2 lub 3 na identyfikator wstępnego wczytywania.

Opcjonalnie: zatrzymywanie wstępnego wczytywania reklam

Jeśli nie musisz już wyświetlać reklam dla określonego identyfikatora wstępnego wczytywania w sesji, możesz zatrzymać wstępne wczytywanie reklam. Aby zatrzymać wczytywanie reklam dla określonego identyfikatora wstępnego wczytywania, wywołaj metodę destroy() z identyfikatorem wstępnego wczytywania. Wywołanie metody destroy() usuwa z pamięci podręcznej wszystkie wstępnie wczytane reklamy powiązane z identyfikatorem wstępnego wczytywania.

Ten przykład pokazuje, jak zatrzymać wstępne wczytywanie reklam:

Kotlin

private fun stopPreloading(adUnitId: String) {
  // Stops the preloading and destroy preloaded ads.
  RewardedInterstitialAdPreloader.destroy(adUnitId)
}

Java

private void stopPreloading(String adUnitId) {
  // Stops the preloading and destroy preloaded ads.
  RewardedInterstitialAdPreloader.destroy(adUnitId);
}

Opcjonalnie: odczytywanie informacji o odpowiedzi

Odczytaj informacje o odpowiedzi na następną wstępnie wczytaną reklamę bez usuwania jej z pamięci podręcznej.

Ten przykład pokazuje, jak odczytać informacje o odpowiedzi na następną wstępnie wczytaną reklamę:

Kotlin

val responseInfo = RewardedInterstitialAdPreloader.peekAdResponseInfo(preloadId)
if (responseInfo == null) {
  Log.e(TAG, "Failed to peek ad response info.")
  return
}

Log.d(TAG, "Peeked ad response ID: ${responseInfo.responseId}")

Java

ResponseInfo responseInfo = RewardedInterstitialAdPreloader.peekAdResponseInfo(preloadId);
if (responseInfo == null) {
  Log.e(TAG, "Failed to peek ad response info.");
  return;
}

Log.d(TAG, "Peeked ad response ID: " + responseInfo.getResponseId());