Konfigurowanie reklam wyświetlanych przy otwarciu aplikacji

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

Reklamy wyświetlane przy otwarciu aplikacji to format 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 otwierają aplikację na pierwszym planie, wyświetlaj reklamy przy otwarciu aplikacji.

Więcej informacji znajdziesz w wytycznych dotyczących 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: ca-app-pub-3940256099942544/9257395921.
    • Podczas tworzenia i testowania aplikacji używaj reklam testowych, a nie gotowych 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.
    • Szczegółowe informacje o reklamach testowych w GMA Next-Gen SDK znajdziesz w artykule Włączanie reklam testowych.

Wstępne ładowanie reklam (beta)

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

Wstępne ładowanie reklam zapewnia te korzyści:

  • Zarządzanie plikami referencyjnymi: przechowuje pliki referencyjne do momentu wyświetlenia reklam.
  • Automatyczne ponowne wczytywanie: wczytuje nową reklamę, gdy poprzednia zostanie pobrana z pamięci podręcznej.
  • Zarządzane ponowne próby: wczytuje nową reklamę, gdy nie uda się wczytać poprzedniej.
  • Obsługa wygasania: odświeża reklamy przed wygaśnięciem.
  • Optymalizacja pamięci podręcznej: optymalizuje kolejność pamięci podręcznej, aby wyświetlać reklamy o najwyższym priorytecie.

Rozpoczynanie 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)
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.

Poprzedni przykład pokazuje, jak używać identyfikatora jednostki reklamowej jako identyfikatora wstępnego wczytywania. Identyfikator wstępnego ładowania to ciąg znaków, który tworzysz, aby identyfikować konfigurację wstępnego ładowania reklam. Jeśli 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

Przed wyświetleniem reklamy 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 nie ma dostępnej reklamy, 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 załadowaną 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 osiągnie miejsce docelowe 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 przed wyświetleniem reklamy musisz sprawdzić jej metadane, odczytaj informacje o odpowiedzi bez usuwania reklamy z pamięci podręcznej.

Nasłuchiwanie zdarzeń reklamowych

Przed wyświetleniem reklamy nasłuchuj zdarzeń reklamowych. Przykład poniżej pokazuje, jak zarejestrować wywołania zwrotne w przypadku 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 ładowania

Gdy zaczniesz wstępnie ładować reklamy, zarejestruj się na zdarzenia wstępnego ładowania, aby otrzymywać powiadomienia o pomyślnym wstępnym załadowaniu reklam, niepowodzeniu wstępnego ładowania lub wyczerpaniu pamięci podręcznej reklam.

Poniższy przykład pokazuje, jak zarejestrować się na potrzeby zdarzeń reklamowych związanych ze wstępnym wczytywaniem:

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 w przypadku wstępnie wczytanych konfiguracji. Nie wywołuj żądań ręcznego wczytywania 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 reklam

Jeśli chcesz wiedzieć, czy reklama jest dostępna, sprawdź jej dostępność. Ten przykład sprawdza, 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ć wykorzystanie 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 załadowane reklamy. Jeśli większość ruchu pochodzi z urządzeń z małą 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)
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 wstępnego buforowania

GMA Next-Gen SDK wymusza limit łącznej 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 załadowanych reklam. Ten limit jest wspólny dla wszystkich formatów i identyfikatorów wstępnego wczytywania.
  • Zalecamy zachowanie rozmiaru bufora równego 2 dla każdego identyfikatora wstępnego wczytywania.

Opcjonalnie: zatrzymywanie wstępnego wczytywania reklam

Utrzymuj wstępne wczytywanie aktywne, gdy aplikacja wyświetla reklamy. W tym czasie nie używaj metody destroy. Jeśli nie musisz już wyświetlać reklam o określonym identyfikatorze wstępnego wczytywania w danej 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 powoduje usunięcie z pamięci podręcznej wszystkich wstępnie załadowanych reklam powiązanych z identyfikatorem wstępnego ładowania.

Poniższy przykład pokazuje, 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: przeczytaj informacje o odpowiedziach

Odczytaj informacje o odpowiedzi na następną wstępnie załadowaną reklamę 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 następnej wstępnie załadowanej odpowiedzi na reklamę:

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 uruchomień „na zimno” i ekranów wczytywania

Uruchomienie „na zimno” ma miejsce, gdy aplikacja jest uruchamiana z dysku, a uruchomienie częściowo z pamięci – gdy otwierasz aplikację ponownie z pamięci. Podczas uruchamiania „na zimno” nie masz wstępnie załadowanej reklamy, którą można od razu wyświetlić. Podczas ciepłego startu możesz mieć już gotową do wyświetlenia wstępnie załadowaną reklamę.

Podczas uruchamiania „na zimno” użytkownicy mogą wejść w interakcję z aplikacją, zanim się ona załaduje i wyświetli reklamę. Aby zapewnić użytkownikom wygodę, wyświetlaj reklamy przy otwarciu aplikacji podczas uruchamiania „na zimno” wyłącznie na ekranie wczytywania, gdy wczytują się zasoby aplikacji. Jeśli wczytywanie zasobów zostanie zakończone i użytkownik dotrze do głównej treści, zanim reklama się wczyta, nie wyświetlaj reklamy.

Rekomendacje

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

  • Nie pokazuj reklamy wyświetlanej przy otwarciu aplikacji przy pierwszym uruchomieniu aplikacji.
  • Jeśli ekran wczytywania zakończy wczytywanie, gdy reklama jest wyświetlana, zamknij go 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.