Konfigurowanie reklam pełnoekranowych z nagrodą

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

Reklamy pełnoekranowe z nagrodą to format, który umożliwia oferowanie nagród za oglądanie reklam wyświetlających się automatycznie w naturalnych momentach przejściowych aplikacji. W przeciwieństwie do reklam z nagrodą użytkownicy nie muszą wyrażać 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:

  • Skonfiguruj GMA Next-Gen SDK.
  • Użyj identyfikatora testowej jednostki pełnoekranowej reklamy z nagrodą ca-app-pub-3940256099942544/5354046379.
    • Podczas tworzenia i testowania aplikacji używaj reklam testowych zamiast reklam gotowych. Jeśli nie użyjesz testowego identyfikatora jednostki reklamowej, Google może zawiesić Twoje konto.
    • Zanim opublikujesz aplikację, zastąp ten identyfikator identyfikatorem jednostki reklamowej.
    • Szczegółowe informacje o GMA Next-Gen SDK reklamach testowych znajdziesz w artykule Włączanie reklam testowych.

Wstępne ładowanie reklam (beta)

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

Wstępne wczytywanie reklam zapewnia te korzyści:

  • Zarządzanie plikami referencyjnymi: utrzymuje pliki referencyjne do momentu wyświetlenia reklam.
  • Automatyczne ponowne wczytywanie: wczytuje nową reklamę, gdy jedna z nich zostanie pobrana z pamięci podręcznej.
  • Zarządzane ponawianie: wczytuje nową reklamę, gdy nie uda się wczytać poprzedniej.
  • Obsługa wygaśnięcia: odświeża reklamy przed wygaśnięciem.
  • Optymalizacja pamięci podręcznej: optymalizuje kolejność w pamięci podręcznej, aby wyświetlać reklamy o najwyższym priorytecie.
Uwaga: aby wczytać reklamy ręcznie, zapoznaj się z artykułem Wczytywanie pojedynczej reklamy pełnoekranowej z nagrodą.

Rozpocznij wstępne ładowanie 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.

Poniższy przykład pokazuje, jak rozpocząć wstępne wczytywanie reklam:

Kotlin

private fun startPreloading(adUnitId: String) {
  // 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

private void startPreloading(String adUnitId) {
  // 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 pokazano, 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 identyfikowania konfiguracji wstępnego ładowania reklam. Jeśli Twoja aplikacja wymaga wielu konfiguracji kierowania dla tego samego identyfikatora 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, funkcja 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. Poniższy 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());
      });
}

Dopóki nie będziesz gotowy(-a) do wyświetlenia reklamy, nie wywołuj metody pollAd(). Aby przeczytać informacje o odpowiedzi na żądanie reklamy bez wyświetlania jej, zobacz Odczytywanie informacji o odpowiedzi.

Nasłuchiwanie zdarzeń reklamowych

Przed wyświetleniem reklamy nasłuchuj zdarzeń związanych z reklamą. W tym przykładzie rejestrujemy wywołania zwrotne 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. Serwery reklam Google przekazują dowolną wartość ciągu znaków ustawioną w obiekcie reklamy do parametru zapytania custom_data wywołania zwrotnego SSV. Jeśli nie ustawiono wartości danych niestandardowych, wartość parametru zapytania custom_data nie jest obecna w wywołaniu zwrotnym SSV.

W tym przykładzie przed wyświetleniem reklamy ustawiamy dane niestandardowe w obiekcie 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 własnymi danymi.

Opcjonalnie: nasłuchiwanie zdarzeń wstępnego wczytywania

Gdy zaczniesz wstępnie wczytywać reklamy, zarejestruj się, aby otrzymywać powiadomienia o zdarzeniach wstępnego wczytywania. Będziesz wtedy wiedzieć, kiedy reklamy zostaną wstępnie wczytane, kiedy nie uda się ich wstępnie wczytać lub kiedy wyczerpie się pamięć podręczna reklam.

Ten przykład pokazuje, jak zarejestrować się w celu otrzymywania zdarzeń związanych z wstępnym wczytywaniem 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 wstępnie wczytanych konfiguracji.

Opcjonalnie: sprawdzanie dostępności reklamy

Jeśli chcesz sprawdzić, czy reklama jest dostępna, sprawdź jej dostępność. W tym przykładzie sprawdzamy, 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: ustaw rozmiar bufora

Rozmiar bufora określa liczbę wstępnie wczytanych reklam przechowywanych w pamięci. Domyślnie Google optymalizuje rozmiar bufora, aby zachować równowagę między zużyciem pamięci a opóźnieniem wyświetlania reklam. Możesz ustawić niestandardowy rozmiar bufora, aby zwiększyć liczbę reklam przechowywanych w pamięci. Zalecamy rozmiar bufora wynoszący 2 wstępnie wczytane reklamy.

W przykładzie poniżej pokazujemy, jak ustawić rozmiar bufora:

Kotlin

private fun setBufferSize(adUnitId: String) {
  val adRequest = AdRequest.Builder(adUnitId).build()
  // Define a PreloadConfiguration and set the buffer size to 2 preloaded ads.
  val preloadConfig = PreloadConfiguration(adRequest, bufferSize = 2)
  RewardedInterstitialAdPreloader.start(adUnitId, preloadConfig)
}

Java

private void setBufferSize(String adUnitId) {
  AdRequest adRequest = new AdRequest.Builder(adUnitId).build();
  // Define a PreloadConfiguration and set the buffer size to 2 preloaded ads.
  PreloadConfiguration preloadConfig = new PreloadConfiguration(adRequest, 2);
  RewardedInterstitialAdPreloader.start(adUnitId, preloadConfig);
}

Limity wstępnego buforowania

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

  • Limit domyślny: 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 zachowanie rozmiaru bufora wynoszącego 2 w przypadku każdego identyfikatora wstępnego wczytywania.

Opcjonalnie: zatrzymywanie wstępnego wczytywania reklam

Jeśli nie chcesz ponownie wyświetlać reklam dla określonego identyfikatora wstępnego wczytywania w sesji, możesz zatrzymać wstępne wczytywanie reklam. Aby przestać wczytywać reklamy dla określonego identyfikatora wstępnego wczytywania, wywołaj metodę destroy() z identyfikatorem wstępnego wczytywania. Wywołanie metody destroy() powoduje usunięcie z pamięci podręcznej wszystkich wstępnie wczytanych reklam powiązanych z identyfikatorem wstępnego wczytywania.

Poniższy 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: przeczytaj informacje o odpowiedzi

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

Ten przykład pokazuje, jak odczytać informacje o odpowiedzi na żądanie wstępnie wczytanej reklamy:

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