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ą ca-app-pub-3940256099942544/5224354917.
    • Podczas tworzenia i testowania aplikacji używaj reklam testowych, a nie aktywnych 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.
    • Więcej informacji o reklamach testowych GMA Next-Gen SDK znajdziesz w artykule Włączanie reklam testowych.

Wstępne ładowanie reklam (beta)

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

Wstępne wczytywanie reklam zapewnia te korzyści:

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

Rozpoczęcie 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

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 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 zidentyfikować 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.

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

Pobieranie i wyświetlanie wstępnie wczytanej reklamy

Zanim wyświetlisz reklamę, wywołaj metodę pollAd. Nie przechowuj obiektu wstępnie wczytanej reklamy. 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 żadna reklama nie jest dostępna, GMA Next-Gen SDK nie zwróci żadnej reklamy.

Gdy masz dostępny obiekt reklamy, wywołaj metodę show, aby wyświetlić reklamę. Użyj detektora zdarzeń po otrzymaniu nagrody, aby obsługiwać zdarzenia po otrzymaniu nagrody. 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 = 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());
      });
}

Gdy aplikacja dotrze do miejsca docelowego 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 musisz sprawdzić metadane reklamy przed jej wyświetleniem, odczytaj informacje o odpowiedzi bez usuwania reklamy z pamięci podręcznej.

Nasłuchiwanie zdarzeń związanych z reklamami

Zanim wyświetlisz reklamę, nasłuchuj zdarzeń związanych z reklamami. Poniższy 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: sprawdzanie wywołań zwrotnych weryfikacji po stronie serwera (SSV)

Aby przekazać kontekst użytkownika i aplikacji w wywołaniach zwrotnych weryfikacji po stronie serwera (SSV), przed wyświetleniem reklamy ustaw opcje weryfikacji w obiekcie reklamy. Ponieważ wywołania zwrotne SSV docierają do Twojego serwera z Google bez stanu sesji, 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ć nagrodę, np. wewnętrzny identyfikator konta.
  • Parametr zapytania custom_data: zawiera dane aplikacji, takie jak miejsce docelowe nagrody, poziom gry lub wygenerowany przez serwer nonce.

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

Poniższy przykład ustawia dane niestandardowe w obiekcie reklamy 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.

Ważne: parametr zapytania custom_data jest zakodowany w procentach. Zanim przeanalizujesz wartość, zdekoduj ciąg znaków na serwerze i sprawdź podpis wywołania zwrotnego, zanim zaufasz parametrom zapytania user_id lub custom_data.

Opcjonalnie: nasłuchiwanie zdarzeń wstępnego wczytywania

Gdy rozpoczniesz wstępne ładowanie reklam, zarejestruj się, aby otrzymywać powiadomienia o zdarzeniach wstępnego ładowania, gdy reklamy zostaną wstępnie załadowane, nie uda się ich wstępnie załadować lub wyczerpie się pamięć podręczna reklam.

Poniższy 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. Nie wywołuj ręcznych żądań wczytania 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 reklamy

Jeśli musisz sprawdzić, czy reklama jest dostępna, sprawdź jej dostępność. Poniższy 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 opóźnienie wyświetlania reklam. Możesz ustawić niestandardowy rozmiar bufora, aby zwiększyć lub zmniejszyć liczbę reklam przechowywanych w pamięci. Zalecamy ustawienie rozmiaru bufora na 2 wstępnie wczytane reklamy. Jeśli większość ruchu pochodzi z urządzeń o małej ilości pamięci, zmniejsz rozmiar bufora.

Poniższy 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 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

Podczas wyświetlania reklam przez aplikację pozostaw wstępne wczytywanie aktywne. W tym czasie nie używaj metody destroy. 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 spowoduje 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.
  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 następnej wstępnie wczytanej reklamy 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 odpowiedzi następnej wstępnie wczytanej reklamy:

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