Konfigurowanie reklam wyświetlanych przy otwarciu aplikacji

Pakiet SDK.

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

Reklamy wyświetlane przy otwarciu aplikacji to format reklamowy przeznaczony dla wydawców, którzy chcą zarabiać na ekranach wczytywania aplikacji. Reklamy wyświetlane przy otwarciu aplikacji można w każdej chwili zamknąć. Są one wyświetlane, gdy użytkownicy przenoszą aplikację na pierwszy plan.

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 ca-app-pub-3940256099942544/9257395921.
    • Podczas tworzenia i testowania aplikacji używaj reklam testowych, a nie reklam aktywnych. 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 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ę startPreload() raz na początku aplikacji. Po wywołaniu metody startPreload() pakiet 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

private fun startPreloading(adUnitId: String) {
  val adRequest = AdRequest.Builder(adUnitId).build()
  val preloadConfig = PreloadConfiguration(adRequest)
  AppOpenAdPreloader.start(adUnitId, preloadConfig)
}

Java

private void startPreloading(String adUnitId) {
  AdRequest adRequest = new AdRequest.Builder(adUnitId).build();
  PreloadConfiguration preloadConfig = new PreloadConfiguration(adRequest);
  AppOpenAdPreloader.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 w celu identyfikacji konfiguracji 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ę. 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 = 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);
}

Nie wywołuj metody pollAd() do momentu, aż będziesz gotowy(-a) do wyświetlenia reklamy. Aby odczytać informacje o odpowiedzi na reklamę bez jej wyświetlania, zapoznaj się z sekcją Odczytywanie informacji o odpowiedzi.

Nasłuchiwanie zdarzeń reklamowych

Zanim wyświetlisz reklamę, nasłuchuj zdarzeń reklamowych. Poniższy przykład pokazuje, jak zarejestrować wywołania zwrotne dla 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 zaczniesz wstępnie wczytywać reklamy, 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 wyczerpie się pamięć podręczna reklam.

Poniższy przykład pokazuje, jak zarejestrować się, aby otrzymywać powiadomienia o zdarzeniach wstępnego wczytywania reklam:

Kotlin

private fun startPreloadingWithCallback(adUnitId: String) {
  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

private void startPreloadingWithCallback(String adUnitId) {
  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.

Opcjonalnie: sprawdzanie dostępności reklam

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

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

Kotlin

private fun setBufferSize(adUnitId: String) {
  val adRequest = AdRequest.Builder(adUnitId).build()
  // Four is the recommended maximum buffer size.
  val preloadConfig = PreloadConfiguration(adRequest, bufferSize = 4)
  AppOpenAdPreloader.start(adUnitId, preloadConfig)
}

Java

private void setBufferSize(String adUnitId) {
  AdRequest adRequest = new AdRequest.Builder(adUnitId).build();
  // Four is the recommended maximum buffer size.
  PreloadConfiguration preloadConfig = new PreloadConfiguration(adRequest, 4);
  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, aby rozmiar bufora wynosił 2 lub 3 na identyfikator wstępnego wczytywania.

Opcjonalnie: zatrzymywanie wstępnego wczytywania reklam

Jeśli nie musisz ponownie 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.

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: odczytywanie informacji o odpowiedzi

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

Poniższy przykład pokazuje, jak odczytać informacje o odpowiedzi na następną wstępnie wczytaną 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());

Uruchamianie „na zimno” i ekrany wczytywania

Uruchomienie „na zimno” następuje, gdy aplikacja uruchamia się od nowa, np. gdy użytkownik otwiera aplikację po raz pierwszy lub po zakończeniu działania pamięci. Podczas uruchamiania „na zimno” nie masz wcześniej wczytanej reklamy wyświetlanej przy otwarciu aplikacji, którą można od razu wyświetlić.

Ze względu na opóźnienia w żądaniach reklam użytkownicy mogą wejść w interakcję z aplikacją, zanim pojawi się reklama wyświetlana przy otwarciu aplikacji. Aby uniknąć pogorszenia wrażeń użytkowników, wyświetlaj reklamy wyświetlane przy otwarciu aplikacji podczas uruchamiania „na zimno” tylko na ekranie wczytywania, gdy wczytują się zasoby aplikacji. Jeśli wczytywanie zasobów się zakończy, a użytkownik dotrze do głównej treści, zanim wczyta się reklama, nie wyświetlaj reklamy.

Wczytuj zasoby aplikacji w wątku w tle, aby wczytywanie trwało podczas wyświetlania reklamy.

Sprawdzone metody

Postępuj zgodnie z tymi sprawdzonymi metodami dotyczącymi reklam wyświetlanych przy otwarciu aplikacji:

  • Pokazuj pierwszą reklamę wyświetlaną przy otwarciu aplikacji dopiero wtedy, gdy użytkownik otworzy Twoją aplikację kilka razy.
  • Wyświetlaj reklamy wyświetlane przy otwarciu aplikacji tylko wtedy, gdy użytkownicy czekają na wczytanie aplikacji.
  • Jeśli ekran wczytywania zakończy wczytywanie podczas wyświetlania reklamy, zamknij go w metodzie wywołania zwrotnego po zamknięciu reklamy.