Konfigurowanie reklam pełnoekranowych

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

Reklamy pełnoekranowe zakrywają interfejs aplikacji. Wyświetlają się one 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.

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 /6499/example/interstitial.
    • Podczas tworzenia i testowania aplikacji używaj reklam testowych, a nie 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 swojej jednostki reklamowej.
    • Więcej informacji o reklamach testowych GMA Next-Gen SDK znajdziesz w artykule Włączanie reklam testowych.

Informacje o wstępnym ładowaniu reklam

Wstępne ładowanie reklam 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.

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

// 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

// 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 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ę. 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 = 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);
}

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

Nasłuchiwanie zdarzeń reklamowych

Zanim wyświetlisz reklamę, nasłuchuj zdarzeń reklamowych. Ten przykład pokazuje, jak zarejestrować wywołania zwrotne dla 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 wczytywanie reklam, zarejestruj się, aby otrzymywać powiadomienia o zdarzeniach wstępnego wczytywania, gdy reklamy zostaną wstępnie wczytane, nie uda się ich wstępnie wczytać lub gdy pamięć podręczna reklam zostanie wyczerpana.

Ten przykład pokazuje, 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.

Opcjonalnie: sprawdzanie dostępności reklam

Jeśli chcesz sprawdzić, czy reklama jest dostępna, sprawdź jej dostępność. Ten przykład pokazuje, jak sprawdzić, 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ć liczbę reklam przechowywanych w pamięci. Zalecamy maksymalny rozmiar bufora wynoszący 4.

Ten przykład pokazuje, jak ustawić rozmiar bufora na 4 wstępnie wczytane reklamy:

Kotlin

val adRequest = AdRequest.Builder(adUnitId).build()
// Maintain small or default buffer size unless rapid transitions are expected.
val preloadConfig = PreloadConfiguration(adRequest, bufferSize = 2)
InterstitialAdPreloader.start(adUnitId, preloadConfig)

Java

// Maintain small or default buffer size unless rapid transitions are expected.
AdRequest adRequest = new AdRequest.Builder(adUnitId).build();
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 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, aby rozmiar bufora wynosił 2 lub 3 na identyfikator 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.
  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 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 = 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());