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ą wyrazić zgody na wyświetlenie reklamy pełnoekranowej z nagrodą. Więcej informacji znajdziesz w wytycznych dotyczących reklam 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 pełnoekranowej reklamy z nagrodą: ca-app-pub-3940256099942544/5354046379.
    • Podczas tworzenia i testowania aplikacji używaj reklam testowych, a nie gotowych reklam produkcyjnych. Jeśli nie użyjesz identyfikatora testowej jednostki reklamowej, Google może zawiesić Twoje konto.
    • Zanim opublikujesz aplikację, zastąp ten identyfikator identyfikatorem jednostki reklamowej.
    • Szczegółowe informacje o reklamach testowych w GMA Next-Gen SDK znajdziesz w artykule Włączanie reklam testowych.

Wstępne ładowanie reklam (beta)

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

Wstępne ładowanie reklam zapewnia te korzyści:

  • Zarządzanie plikami referencyjnymi: przechowuje pliki referencyjne do momentu wyświetlenia reklam.
  • Automatyczne ponowne wczytywanie: wczytuje nową reklamę, gdy poprzednia zostanie pobrana z pamięci podręcznej.
  • Zarządzane ponowne próby: wczytuje nową reklamę, gdy nie uda się wczytać poprzedniej.
  • Obsługa wygasania: odświeża reklamy przed wygaśnięciem.
  • Optymalizacja pamięci podręcznej: optymalizuje kolejność pamięci podręcznej, aby wyświetlać reklamy o najwyższym priorytecie.

Rozpoczynanie wstępnego ładowania reklam

Aby rozpocząć wstępne wczytywanie reklam, wywołaj metodę start raz podczas inicjowania GMA Next-Gen SDK. Po wywołaniu metody start 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.

Poprzedni przykład pokazuje, jak używać identyfikatora jednostki reklamowej jako identyfikatora wstępnego wczytywania. Identyfikator wstępnego ładowania to ciąg znaków, który tworzysz, aby identyfikować konfigurację wstępnego ładowania reklam. Jeśli aplikacja wymaga wielu konfiguracji kierowania dla tego samego identyfikatora jednostki reklamowej, przekaż niestandardowy identyfikator ciągu znaków.

Wstępne ładowanie reklam nie obsługuje zmiany parametrów kierowania ani żądań reklam. Jeśli musisz zmienić parametry kierowania między żądaniami, użyj pojedynczego wczytywania.

Pobieranie i wyświetlanie wstępnie wczytanej reklamy

Przed wyświetleniem reklamy wywołaj metodę pollAd. Nie przechowuj wstępnie wczytanego obiektu reklamowego. Gdy wywołasz metodę pollAd, GMA Next-Gen SDK pobierze dostępną reklamę i automatycznie wstępnie wczyta następną reklamę w tle. Jeśli nie ma dostępnej reklamy, 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 po otrzymaniu nagrody. Poniższy przykład pokazuje, jak pobrać i wyświetlić wstępnie załadowaną 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());
      });
}

Gdy aplikacja osiągnie miejsce docelowe reklamy i będzie mogła wywołać metodę show, wywołaj metodę pollAd. Nie wywołuj metody pollAd w wywołaniach zwrotnych wstępnego wczytywania ani po sprawdzeniu metody isAdAvailable, aby wstrzymać reklamę. Jeśli przed wyświetleniem reklamy musisz sprawdzić jej metadane, odczytaj informacje o odpowiedzi bez usuwania reklamy z pamięci podręcznej.

Nasłuchiwanie zdarzeń reklamowych

Przed wyświetleniem reklamy nasłuchuj zdarzeń reklamowych. Przykład poniżej pokazuje, jak zarejestrować wywołania zwrotne w przypadku zdarzeń reklamowych:

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: sprawdzanie wywołań zwrotnych weryfikacji po stronie serwera (SSV)

Aby przekazywać kontekst użytkownika i aplikacji w wywołaniach zwrotnych weryfikacji po stronie serwera (SSV), przed wyświetleniem reklamy ustaw opcje weryfikacji w obiekcie reklamy. Wywołania zwrotne SSV docierają do Twojego serwera z Google bez stanu sesji, dlatego dołącz te opcjonalne ciągi znaków. Google przekazuje te ciągi znaków bez zmian jako podpisane parametry zapytania w wywołaniu zwrotnym SSV.

  • Parametr zapytania user_id: identyfikuje użytkownika, któremu należy przyznać środki, np. identyfikator konta wewnętrznego.
  • Parametr zapytania custom_data: zawiera dane aplikacji, takie jak miejsce docelowe nagrody, poziom gry lub liczba jednorazowa wygenerowana przez serwer.

Jeśli nie ustawisz wartości, Google pominie ten parametr zapytania w wywołaniu zwrotnym SSV.

Poniższy przykład pokazuje, jak ustawić dane niestandardowe w obiekcie reklamy przed jej wyświetleniem:

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 danymi niestandardowymi.

Ważna uwaga: parametr zapytania custom_data jest zakodowany procentowo. Zanim przeanalizujesz wartość, zdekoduj adres URL ciągu na serwerze i zweryfikuj podpis wywołania zwrotnego, zanim zaufasz parametrom zapytania user_id lub custom_data.

Opcjonalnie: nasłuchiwanie zdarzeń wstępnego ładowania

Gdy zaczniesz wstępnie ładować reklamy, zarejestruj się na zdarzenia wstępnego ładowania, aby otrzymywać powiadomienia o pomyślnym wstępnym załadowaniu reklam, niepowodzeniu wstępnego ładowania lub wyczerpaniu pamięci podręcznej reklam.

Poniższy przykład pokazuje, jak zarejestrować się na potrzeby zdarzeń reklamowych związanych ze wstępnym wczytywaniem:

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 w przypadku wstępnie wczytanych konfiguracji. Nie wywołuj żądań ręcznego wczytywania w wywołaniach zwrotnych dotyczących niepowodzenia. W metodach wywołania zwrotnego zdarzenia wstępnego ładowania nie wywołuj metod pollAd, destroy ani start. Wywołanie tych metod w wywołaniach zwrotnych może spowodować rekurencyjne pętle wczytywania.

Opcjonalnie: sprawdzanie dostępności reklam

Jeśli chcesz wiedzieć, 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 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ć wykorzystanie pamięci i opóźnienie wyświetlania reklam. Możesz ustawić niestandardowy rozmiar bufora, aby zwiększyć lub zmniejszyć liczbę reklam przechowywanych w pamięci. Zalecamy rozmiar bufora wynoszący 2 wstępnie załadowane reklamy. Jeśli większość ruchu pochodzi z urządzeń z małą ilością pamięci, zmniejsz rozmiar bufora.

Poniższy przykład pokazuje, 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 limit łącznej 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 załadowanych reklam. Ten limit jest wspólny dla wszystkich formatów i identyfikatorów wstępnego wczytywania.
  • Zalecamy zachowanie rozmiaru bufora równego 2 dla każdego identyfikatora wstępnego wczytywania.

Opcjonalnie: zatrzymywanie wstępnego wczytywania reklam

Utrzymuj wstępne wczytywanie aktywne, gdy aplikacja wyświetla reklamy. W tym czasie nie używaj metody destroy. Jeśli nie musisz już wyświetlać reklam o określonym identyfikatorze wstępnego wczytywania w danej 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 powoduje usunięcie z pamięci podręcznej wszystkich wstępnie załadowanych reklam powiązanych z identyfikatorem wstępnego ładowania.

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 odpowiedziach

Odczytaj informacje o odpowiedzi na następną wstępnie załadowaną reklamę bez usuwania jej z pamięci podręcznej. Jeśli przed wyświetleniem reklamy musisz sprawdzić jej metadane, odczytaj informacje o odpowiedzi, zamiast wywoływać metodę pollAd.

Poniższy przykład pokazuje, jak odczytać informacje o następnej wstępnie załadowanej odpowiedzi na 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());