Konfigurowanie reklam pełnoekranowych

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

Reklamy pełnoekranowe zakrywają interfejs aplikacji. Wyświetlaj je w naturalnych momentach przejściowych w aplikacji, np. między działaniami lub podczas przerw między poziomami gry.

Gdy aplikacja wyświetla reklamę pełnoekranową, użytkownicy mogą w nią kliknąć i przejść dalej lub zamknąć reklamę i wrócić do aplikacji. Przeczytaj to studium przypadku.

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

Zanim zaczniesz

Zanim przejdziesz dalej, wykonaj te czynności:

  • Skonfiguruj GMA Next-Gen SDK.
  • Użyj identyfikatora testowej jednostki reklamowej pełnoekranowej ca-app-pub-3940256099942544/1033173712.
    • 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.

W przykładzie poniżej pokazujemy, 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)
  InterstitialAdPreloader.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);
  InterstitialAdPreloader.start(adUnitId, preloadConfig);
}

Zastąp AD_UNIT_ID identyfikatorem jednostki reklamowej.

W poprzednim przykładzie pokazujemy, 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ń reklam. 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 reklamowy, wywołaj metodę show, aby wyświetlić reklamę. W przykładzie poniżej pokazujemy, 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 = InterstitialAdPreloader.pollAd(adUnitId)
  if (ad == null) {
    Log.e(TAG, "Interstitial ad is not available.")
    return
  }

  // Interact with the ad object as needed.
  Log.d(TAG, "Interstitial ad response info: ${ad.getResponseInfo()}")
  ad.adEventCallback =
    object : InterstitialAdEventCallback {
      override fun onAdImpression() {
        Log.d(TAG, "Interstitial ad recorded an impression.")
      }
    }
  ad.show(activity)
}

Java

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

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

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

  // Show the ad.
  ad.show(activity);
}

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ń reklamowych

Zanim wyświetlisz reklamę, nasłuchuj zdarzeń reklamowych. W przykładzie poniżej rejestrujemy wywołania zwrotne zdarzeń reklamowych:

Kotlin

// Listen for ad events.
val ad = interstitialAd
if (ad == null) {
  Log.e(TAG, "Interstitial ad is not ready yet.")
  return
}

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

    override fun onAdDismissedFullScreenContent() {
      // Interstitial ad did dismiss.
      interstitialAd = null
    }

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

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

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

Java

// Listen for ad events.
if (interstitialAd == null) {
  Log.e(TAG, "Interstitial ad is not ready yet.");
  return;
}

interstitialAd.setAdEventCallback(
    new InterstitialAdEventCallback() {
      @Override
      public void onAdShowedFullScreenContent() {
        // Interstitial ad did show.
      }

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

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

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

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

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 gdy wyczerpie się pamięć podręczna reklam.

W przykładzie poniżej pokazujemy, 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,
        ("Interstitial preload ad $preloadId failed to load with error: ${adError.message}"),
      )
    }

    override fun onAdsExhausted(preloadId: String) {
      Log.i(TAG, "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, "Interstitial preload ad $preloadId is available")
    }
  }
val adRequest = AdRequest.Builder(adUnitId).build()
val preloadConfig = PreloadConfiguration(adRequest)
InterstitialAdPreloader.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(
                "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, "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, "Interstitial preload ad " + preloadId + " is available");
      }
    };

AdRequest adRequest = new AdRequest.Builder(adUnitId).build();
PreloadConfiguration preloadConfig = new PreloadConfiguration(adRequest);
InterstitialAdPreloader.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 błędów. W metodach wywołań zwrotnych zdarzeń 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 musisz sprawdzić, czy reklama jest dostępna, sprawdź jej dostępność. W przykładzie poniżej sprawdzamy, czy wstępnie wczytana reklama jest dostępna:

Kotlin

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

Java

private boolean isAdAvailable(String adUnitId) {
  return InterstitialAdPreloader.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 rozmiar bufora wynoszący 2 wstępnie wczytane reklamy. Jeśli większość ruchu pochodzi z urządzeń o małej ilości pamięci, zmniejsz rozmiar bufora.

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)
  InterstitialAdPreloader.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);
  InterstitialAdPreloader.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, aby rozmiar bufora dla każdego identyfikatora wstępnego wczytywania wynosił 2.

Opcjonalnie: zatrzymywanie wstępnego wczytywania reklam

Wstępne wczytywanie powinno być aktywne, gdy aplikacja wyświetla reklamy. 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.

W przykładzie poniżej pokazujemy, jak zatrzymać wstępne wczytywanie reklam:

Kotlin

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

Java

private void stopPreloading(String adUnitId) {
  // Stops the preloading and destroy preloaded ads.
  InterstitialAdPreloader.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.

W przykładzie poniżej pokazujemy, jak odczytać informacje o odpowiedzi następnej wstępnie wczytanej reklamy:

Kotlin

val responseInfo = InterstitialAdPreloader.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 = InterstitialAdPreloader.peekAdResponseInfo(preloadId);
if (responseInfo == null) {
  Log.e(TAG, "Failed to peek ad response info.");
  return;
}

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