Konfigurowanie reklam pełnoekranowych

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

Reklamy pełnoekranowe zakrywają interfejs aplikacji. Wyświetlasz 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 kontynuować 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:

  • Skonfiguruj GMA Next-Gen SDK.
  • Użyj identyfikatora testowej jednostki reklamowej pełnoekranowej /21775744923/example/interstitial.
    • Podczas tworzenia i testowania aplikacji używaj reklam testowych zamiast reklam gotowych. Jeśli nie użyjesz testowego identyfikatora jednostki reklamowej, Google może zawiesić Twoje konto.
    • Zanim opublikujesz aplikację, zastąp ten identyfikator identyfikatorem jednostki reklamowej.
    • Szczegółowe informacje o GMA Next-Gen SDK reklamach testowych znajdziesz w artykule Włączanie reklam testowych.

Wstępne ładowanie reklam (beta)

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

Wstępne wczytywanie reklam zapewnia te korzyści:

  • Zarządzanie plikami referencyjnymi: utrzymuje pliki referencyjne do momentu wyświetlenia reklam.
  • Automatyczne ponowne wczytywanie: wczytuje nową reklamę, gdy jedna z nich zostanie pobrana z pamięci podręcznej.
  • Zarządzane ponawianie: wczytuje nową reklamę, gdy nie uda się wczytać poprzedniej.
  • Obsługa wygaśnięcia: odświeża reklamy przed wygaśnięciem.
  • Optymalizacja pamięci podręcznej: optymalizuje kolejność w pamięci podręcznej, aby wyświetlać reklamy o najwyższym priorytecie.
Uwaga: aby wczytać reklamy ręcznie, zapoznaj się z artykułem Wczytywanie pojedynczej reklamy pełnoekranowej.

Rozpocznij wstępne ładowanie reklam

Aby rozpocząć wstępne wczytywanie reklam, wywołaj metodę start raz na początku działania aplikacji. Po wywołaniu metody startGMA 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)
  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 pokazano, jak używać identyfikatora jednostki reklamowej jako identyfikatora wstępnego wczytywania. Identyfikator wstępnego ładowania reklam to ciąg znaków, który tworzysz w celu identyfikowania konfiguracji wstępnego ładowania reklam. Jeśli Twoja aplikacja wymaga wielu konfiguracji kierowania dla tego samego identyfikatora jednostki reklamowej, przekaż niestandardowy identyfikator w postaci 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, funkcja GMA Next-Gen SDK nie zwraca żadnych reklam.

Gdy masz dostępny obiekt reklamy, wywołaj metodę show, aby wyświetlić reklamę. 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 = 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);
}

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

Nasłuchiwanie zdarzeń reklamowych

Przed wyświetleniem reklamy nasłuchuj zdarzeń związanych z reklamą. W tym przykładzie rejestrujemy wywołania zwrotne zdarzeń związanych z reklamami:

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 zaczniesz wstępnie wczytywać reklamy, zarejestruj się, aby otrzymywać powiadomienia o zdarzeniach wstępnego wczytywania. Będziesz wtedy wiedzieć, kiedy reklamy zostaną wstępnie wczytane, kiedy nie uda się ich wstępnie wczytać lub kiedy wyczerpie się pamięć podręczna reklam.

Ten przykład pokazuje, jak zarejestrować się w celu otrzymywania zdarzeń związanych z wstępnym wczytywaniem 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 wstępnie wczytanych konfiguracji.

Opcjonalnie: sprawdzanie dostępności reklamy

Jeśli chcesz sprawdzić, czy reklama jest dostępna, sprawdź jej dostępność. W tym przykładzie 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: ustaw rozmiar bufora

Rozmiar bufora określa liczbę wstępnie wczytanych reklam przechowywanych w pamięci. Domyślnie Google optymalizuje rozmiar bufora, aby zachować równowagę między zużyciem pamięci a opóźnieniem wyświetlania reklam. Możesz ustawić niestandardowy rozmiar bufora, aby zwiększyć liczbę reklam przechowywanych w pamięci. Zalecamy rozmiar bufora wynoszący 2 wstępnie wczytane reklamy.

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 wstępnego buforowania

GMA Next-Gen SDK wymusza w aplikacji limit łącznej liczby wstępnie wczytanych reklam we wszystkich jednostkach reklamowych i identyfikatorach wstępnego wczytywania:

  • Limit domyślny: 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 zachowanie rozmiaru bufora wynoszącego 2 w przypadku każdego identyfikatora wstępnego wczytywania.

Opcjonalnie: zatrzymywanie wstępnego wczytywania reklam

Jeśli nie chcesz ponownie wyświetlać reklam dla określonego identyfikatora wstępnego wczytywania w sesji, możesz zatrzymać wstępne wczytywanie reklam. Aby przestać wczytywać reklamy 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 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.
  InterstitialAdPreloader.destroy(adUnitId)
}

Java

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

Opcjonalnie: przeczytaj informacje o odpowiedzi

Odczytaj informacje o odpowiedzi na kolejną wstępnie wczytaną reklamę bez usuwania jej z pamięci podręcznej.

Ten przykład pokazuje, jak odczytać informacje o odpowiedzi na żądanie 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());