Konfigurowanie reklam wyświetlanych przy otwarciu aplikacji

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

Reklamy wyświetlane przy otwarciu aplikacji to format reklam przeznaczony dla wydawców, którzy chcą zarabiać na ekranach wczytywania aplikacji. Użytkownicy mogą w każdej chwili zamknąć reklamy wyświetlane przy otwarciu aplikacji. Gdy użytkownicy przełączą aplikację na pierwszy plan, wyświetl reklamy wyświetlane przy otwarciu aplikacji.

Więcej informacji znajdziesz w przewodniku dotyczącym reklam wyświetlanych przy otwarciu aplikacji.

Z tego przewodnika dowiesz się, jak zintegrować reklamy wyświetlane przy otwarciu aplikacji z aplikacją na Androida.

Zanim zaczniesz

Zanim przejdziesz dalej, wykonaj te czynności:

  • Skonfiguruj GMA Next-Gen SDK.
  • Użyj identyfikatora testowej jednostki reklamowej wyświetlanej przy otwarciu aplikacji /21775744923/example/app-open.
    • 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 odniesieniami: utrzymuje odniesienia 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

val adRequest = AdRequest.Builder(adUnitId).build()
val preloadConfig = PreloadConfiguration(adRequest)
AppOpenAdPreloader.start(adUnitId, preloadConfig)

Java

AdRequest adRequest = new AdRequest.Builder(adUnitId).build();
PreloadConfiguration preloadConfig = new PreloadConfiguration(adRequest);
AppOpenAdPreloader.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 zmieniać 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 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 żadna reklama nie jest dostępna, GMA Next-Gen SDK nie zwróci żadnych reklam.

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 = AppOpenAdPreloader.pollAd(adUnitId)
  if (ad == null) {
    Log.e(TAG, "App open ad is not available.")
    return
  }

  // Interact with the ad object as needed.
  Log.d(TAG, "App open ad response info: ${ad.getResponseInfo()}")
  ad.adEventCallback =
    object : AppOpenAdEventCallback {
      override fun onAdImpression() {
        Log.d(TAG, "App open 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.
  AppOpenAd ad = AppOpenAdPreloader.pollAd(adUnitId);

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

  Log.d(TAG, "App open ad response info: " + ad.getResponseInfo());
  ad.setAdEventCallback(
      new AppOpenAdEventCallback() {
        @Override
        public void onAdImpression() {
          Log.d(TAG, "App open 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

private fun listenToAdEvents() {
  // Listen for ad events.
  val ad = appOpenAd
  if (ad == null) {
    Log.e(TAG, "App open ad is not ready yet.")
    return
  }

  ad.adEventCallback =
    object : AppOpenAdEventCallback {
      override fun onAdShowedFullScreenContent() {
        // App open ad did show.
      }

      override fun onAdDismissedFullScreenContent() {
        // App open ad did dismiss.
        appOpenAd = null
      }

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

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

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

Java

private void listenToAdEvents() {
  // Listen for ad events.
  if (appOpenAd == null) {
    Log.e(TAG, "App open ad is not ready yet.");
    return;
  }

  appOpenAd.setAdEventCallback(
      new AppOpenAdEventCallback() {
        @Override
        public void onAdShowedFullScreenContent() {
          // App open ad did show.
        }

        @Override
        public void onAdDismissedFullScreenContent() {
          // App open ad did dismiss.
          appOpenAd = null;
        }

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

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

        @Override
        public void onAdClicked() {
          // App open 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 pamięć podręczna reklam zostanie wyczerpana.

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

    override fun onAdsExhausted(preloadId: String) {
      Log.i(TAG, "App open preload ad $preloadId is not available")
    }

    override fun onAdPreloaded(preloadId: String, responseInfo: ResponseInfo) {
      Log.i(TAG, "App open preload ad $preloadId is available")
    }
  }
val adRequest = AdRequest.Builder(adUnitId).build()
val preloadConfig = PreloadConfiguration(adRequest)
AppOpenAdPreloader.start(adUnitId, preloadConfig, preloadCallback)

Java

PreloadCallback preloadCallback =
    new PreloadCallback() {
      @Override
      public void onAdFailedToPreload(@NonNull String preloadId, @NonNull LoadAdError adError) {
        Log.d(
            TAG,
            String.format(
                "App open preload ad %s failed to load with error: %s",
                preloadId, adError.getMessage()));
      }

      @Override
      public void onAdsExhausted(@NonNull String preloadId) {
        Log.i(TAG, String.format("App open preload ad %s is not available", preloadId));
      }

      @Override
      public void onAdPreloaded(@NonNull String preloadId, @NonNull ResponseInfo responseInfo) {
        Log.i(TAG, String.format("App open preload ad %s is available", preloadId));
      }
    };
AdRequest adRequest = new AdRequest.Builder(adUnitId).build();
PreloadConfiguration preloadConfig = new PreloadConfiguration(adRequest);
AppOpenAdPreloader.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 wiedzieć, 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 AppOpenAdPreloader.isAdAvailable(adUnitId)
}

Java

private boolean isAdAvailable(String adUnitId) {
  return AppOpenAdPreloader.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.

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

Limity pamięci podręcznej wstępnego wczytywania

GMA Next-Gen SDK wymusza limit w całej aplikacji dotyczący łącznej 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ę utrzymuj 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.

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.
  AppOpenAdPreloader.destroy(adUnitId)
}

Java

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

Opcjonalnie: odczytywanie informacji o odpowiedzi

Odczytaj informacje o odpowiedzi następnej wstępnie wczytanej reklamy bez usuwania reklamy 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 = AppOpenAdPreloader.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 = AppOpenAdPreloader.peekAdResponseInfo(preloadId);
if (responseInfo == null) {
  Log.e(TAG, "Failed to peek ad response info.");
  return;
}

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

Obsługa uruchamiania „na zimno” i ekranów wczytywania

Uruchamianie „na zimno” ma miejsce, gdy aplikacja jest uruchamiana z dysku, a uruchamianie „na ciepło” – gdy aplikacja jest ponownie otwierana z pamięci. Podczas uruchamiania „na zimno” nie masz wstępnie wczytanej reklamy, którą można od razu wyświetlić. Podczas uruchamiania „na ciepło” możesz mieć wstępnie wczytaną reklamę gotową do wyświetlenia.

Podczas uruchamiania „na zimno” użytkownicy mogą wejść w interakcję z aplikacją, zanim ta wczyta i wyświetli reklamę. Aby uniknąć pogorszenia komfortu użytkowników, wyświetlaj reklamy wyświetlane przy otwarciu aplikacji podczas uruchamiania „na zimno” wyłącznie na ekranie wczytywania, gdy wczytują się zasoby aplikacji. Jeśli wczytywanie zasobów zakończy się, a użytkownik dotrze do głównej treści, zanim wczytywanie reklam się zakończy, nie wyświetlaj reklamy.

Rekomendacje

W przypadku reklam wyświetlanych przy otwarciu aplikacji postępuj zgodnie z tymi zaleceniami:

  • Nie wyświetlaj reklamy wyświetlanej przy otwarciu aplikacji przy pierwszym uruchomieniu aplikacji.
  • Jeśli ekran wczytywania zakończy wczytywanie podczas wyświetlania reklamy, zamknij ekran wczytywania w metodzie wywołania zwrotnego zamknięcia reklamy.
  • Reklamy wyświetlane przy otwarciu aplikacji wygasają po 4 godzinach od wczytania. Nie wyświetlaj reklamy wyświetlanej przy otwarciu aplikacji, która została wczytana ponad 4 godziny temu.