Konfigurowanie reklam z nagrodą

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

Reklamy z nagrodą umożliwiają przekazywanie użytkownikom wirtualnych nagród w aplikacji w zamian za interakcje z reklamami wideo i reklamami demonstracyjnymi gier oraz za wypełnianie ankiet.

Z tego przewodnika dowiesz się, jak zintegrować reklamy 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ą /21775744923/example/rewarded.
    • Podczas tworzenia i testowania aplikacji używaj reklam testowych, a nie reklam rzeczywistych. Jeśli nie użyjesz identyfikatora testowej jednostki reklamowej, Google może zawiesić Twoje konto.
    • Zanim opublikujesz aplikację, zastąp ten identyfikator identyfikatorem swojej jednostki reklamowej.
    • Więcej informacji o reklamach testowych GMA Next-Gen SDK znajdziesz w artykule Włączanie reklam testowych.

Wstępne ładowanie reklam (beta)

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

Wstępne ładowanie reklam zapewnia następujące 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.
Uwaga: aby ręcznie wczytać reklamy, zapoznaj się z artykułem Wczytywanie pojedynczej reklamy z nagrodą.

Rozpoczynanie wstępnego ładowania reklam

Aby rozpocząć wstępne wczytywanie reklam, wywołaj metodę start raz na początku działania aplikacji. Po wywołaniu metody start, 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

val adRequest = AdRequest.Builder(adUnitId).build()
val preloadConfig = PreloadConfiguration(adRequest)
RewardedAdPreloader.start(adUnitId, preloadConfig)

Java

AdRequest adRequest = new AdRequest.Builder(adUnitId).build();
PreloadConfiguration preloadConfig = new PreloadConfiguration(adRequest);
RewardedAdPreloader.start(adUnitId, preloadConfig);

Zastąp AD_UNIT_ID identyfikatorem swojej 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, aby identyfikować konfigurację wstępnego ładowania reklam. Jeśli Twoja aplikacja wymaga wielu konfiguracji kierowania dla tego samego identyfikatora jednostki reklamowej, przekaż niestandardowy identyfikator 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 reklamowy, 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 = RewardedAdPreloader.pollAd(adUnitId)
  if (ad == null) {
    Log.e(TAG, "Rewarded ad is not available.")
    return
  }

  // Interact with the ad object as needed.
  Log.d(TAG, "Rewarded ad response info: ${ad.getResponseInfo()}")
  ad.adEventCallback =
    object : RewardedAdEventCallback {
      override fun onAdImpression() {
        Log.d(TAG, "Rewarded 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 RewardedAd ad = RewardedAdPreloader.pollAd(adUnitId);

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

  Log.d(TAG, "Rewarded ad response info: " + ad.getResponseInfo());
  ad.setAdEventCallback(
      new RewardedAdEventCallback() {
        @Override
        public void onAdImpression() {
          Log.d(TAG, "Rewarded 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 odczytać informacje o odpowiedzi na reklamę bez jej wyświetlania, zapoznaj się z artykułem 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 rejestruje wywołania zwrotne dla zdarzeń związanych z reklamami:

Kotlin

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

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

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

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

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

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

Java

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

  rewardedAd.setAdEventCallback(
      new RewardedAdEventCallback() {
        @Override
        public void onAdShowedFullScreenContent() {
          // Rewarded ad did show.
        }

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

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

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

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

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

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 reklamowym 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.

Ten przykład ustawia dane niestandardowe w obiekcie reklamowym przed wyświetleniem reklamy:

Kotlin

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

Java

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

Zastąp SAMPLE_CUSTOM_DATA_STRING swoimi danymi niestandardowymi.

Opcjonalnie: nasłuchiwanie zdarzeń wstępnego wczytywania

Gdy zaczniesz wstępnie wczytywać reklamy, zarejestruj się, aby otrzymywać powiadomienia o zdarzeniach wstępnego wczytywania, gdy reklamy zostaną wstępnie wczytane, nie uda się ich wstępnie wczytać lub 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 =
  object : PreloadCallback {
    override fun onAdFailedToPreload(preloadId: String, adError: LoadAdError) {
      Log.d(TAG, "Rewarded preload ad $preloadId failed to load with error: ${adError.message}")
    }

    override fun onAdsExhausted(preloadId: String) {
      Log.i(TAG, "Rewarded preload ad $preloadId is not available")
    }

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

Java

PreloadCallback preloadCallback =
    new PreloadCallback() {
      @Override
      public void onAdFailedToPreload(String preloadId, LoadAdError adError) {
        Log.d(
            TAG,
            String.format(
                "Rewarded preload ad %s failed to load with error: %s",
                preloadId, adError.getMessage()));
      }

      @Override
      public void onAdsExhausted(String preloadId) {
        Log.i(TAG, "Rewarded preload ad " + preloadId + " is not available");
      }

      @Override
      public void onAdPreloaded(String preloadId, ResponseInfo responseInfo) {
        Log.i(TAG, "Rewarded preload ad " + preloadId + " is available");
      }
    };

AdRequest adRequest = new AdRequest.Builder(adUnitId).build();
PreloadConfiguration preloadConfig = new PreloadConfiguration(adRequest);
RewardedAdPreloader.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 sprawdza, czy wstępnie wczytana reklama jest dostępna:

Kotlin

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

Java

private boolean isAdAvailable(String adUnitId) {
  return RewardedAdPreloader.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 czas oczekiwania na wyświetlenie reklamy. Możesz ustawić niestandardowy rozmiar bufora, aby zwiększyć liczbę reklam przechowywanych w pamięci. Zalecamy ustawienie rozmiaru bufora na 2 wstępnie wczytane reklamy.

Ten przykład pokazuje, jak ustawić rozmiar bufora:

Kotlin

val adRequest = AdRequest.Builder(adUnitId).build()
// Define a PreloadConfiguration and set the buffer size to 2 preloaded ads.
val preloadConfig = PreloadConfiguration(adRequest, bufferSize = 2)
RewardedAdPreloader.start(adUnitId, preloadConfig)

Java

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);
RewardedAdPreloader.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 utrzymywanie rozmiaru bufora na poziomie 2 dla każdego identyfikatora 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.
  RewardedAdPreloader.destroy(adUnitId)
}

Java

private void stopPreloading(String adUnitId) {
  // Stops the preloading and destroy preloaded ads.
  RewardedAdPreloader.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 = RewardedAdPreloader.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 = RewardedAdPreloader.peekAdResponseInfo(preloadId);
if (responseInfo == null) {
  Log.e(TAG, "Failed to peek ad response info.");
  return;
}

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