Konfigurowanie reklam wyświetlanych przy otwarciu aplikacji

Reklamy wyświetlane przy otwarciu aplikacji pojawiają się, gdy użytkownicy otwierają aplikację lub do niej wracają. Użytkownicy mogą w każdej chwili zamknąć te reklamy. Aby zarabiać na ekranie wczytywania aplikacji, używaj reklam wyświetlanych przy otwarciu aplikacji. Więcej informacji znajdziesz w artykule Wskazówki i sprawdzone metody dotyczące reklam wyświetlanych przy otwarciu aplikacji.

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

Wymagania wstępne

Zanim przejdziesz dalej, wykonaj te czynności:

Android 

ca-app-pub-3940256099942544/9257395921

iOS 

ca-app-pub-3940256099942544/5575463023

Wstępne ładowanie reklam

Wstępne ładowanie reklam w Google Mobile Ads SDK for React Native 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 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ść w pamięci podręcznej, aby wyświetlać reklamy o najwyższym priorytecie.

Aby dowiedzieć się, jak ręcznie wczytywać reklamy, zapoznaj się z przewodnikiem Wczytywanie pojedynczej reklamy wyświetlanej przy otwarciu aplikacji.

Rozpocznij wstępne wczytywanie

Aby rozpocząć wstępne wczytywanie reklam, wywołaj metodę AppOpenAdPreloader.start i przekaż wartość preloadId, ustawienia konfiguracji oraz wywołania zwrotne zdarzeń, aby monitorować zmiany stanu bufora:

export function startAppOpenAdPreloader(
  adUnitId: string,
  preloadId: string,
  customPreloadCallback?: PreloadCallback,
): boolean {
  const started = AppOpenAdPreloader.start(
    preloadId,
    {
      request: {adUnitId},
      bufferSize: 2,
    },
    {
      // Called when an ad is preloaded into the buffer.
      onAdPreloaded: (event) => {
        console.log(`App open ad preloaded for ${event.preloadId}`);
        customPreloadCallback?.onAdPreloaded?.(event);
      },
      // Called when an ad fails to preload.
      onAdFailedToPreload: (error: LoadAdError) => {
        console.error('Failed to preload app open ad:', error.message);
        customPreloadCallback?.onAdFailedToPreload?.(error);
      },
      // Called when all preloaded ads in the buffer have been shown.
      onAdsExhausted: () => {
        console.log('App open ad buffer exhausted.');
        customPreloadCallback?.onAdsExhausted?.();
      },
    },
  );
  return started;
}

preloadId to ciąg znaków, który jednoznacznie identyfikuje konfigurację wstępnego ładowania reklam. Jeśli adUnitId jest używany tylko w jednej konfiguracji wstępnego wczytywania w aplikacji, możesz użyć tego identyfikatora jednostki reklamowej jako identyfikatora wstępnego wczytywania. Jeśli aplikacja wymaga kilku modułów wstępnego wczytywania dla tego samego identyfikatora jednostki reklamowej, przekaż różne ciągi znaków dla każdego identyfikatora wstępnego wczytywania.

Gdy aplikacja pobiera wstępnie załadowaną reklamę z bufora, Google Mobile Ads SDK for React Native wysyła w tle żądanie reklamy zastępczej, aby ponownie wypełnić bufor. Jeśli w buforze nie ma już wstępnie załadowanych reklam, Google Mobile Ads SDK for React Native wywołuje wywołanie zwrotne onAdsExhausted.

Limity wstępnego buforowania

Google Mobile Ads SDK for React Native wymusza limit łącznej liczby wstępnie załadowanych reklam w całej aplikacji:

  • Domyślny limit: Google przechowuje w pamięci maksymalnie 6 wstępnie załadowanych reklam.
  • Zalecamy zachowanie rozmiaru bufora równego 2 dla każdego identyfikatora wstępnego wczytywania.

Jeśli aplikacja osiągnie limit, żądania w tle dotyczące wstępnie wczytanych reklam zostaną wstrzymane, dopóki istniejące reklamy nie zostaną odpytane i wyświetlone lub usunięte.

Ankieta i wyświetlenie reklamy

Aby sprawdzić, czy są dostępne wstępnie wczytane reklamy, i pobrać instancję reklamy, wywołaj metodę AppOpenAdPreloader.pollAd.

Aby nasłuchiwać zdarzeń prezentacji pełnoekranowej, przed wywołaniem metody show zarejestruj wywołania zwrotne we właściwości adEventCallback zwróconej instancji AppOpenAd:

export function showPreloadedAppOpenAd(
  preloadId: string,
  customAdEventCallback?: FullScreenAdEventCallback,
) {
  if (!AppOpenAdPreloader.isAdAvailable(preloadId)) {
    console.log('No preloaded app open ad available right now.');
    return;
  }

  const ad = AppOpenAdPreloader.pollAd(preloadId);
  if (!ad) {
    return;
  }

  ad.adEventCallback = {
    // Called when the ad is presented on screen.
    onAdShowedFullScreenContent: () => {
      console.log('Preloaded app open ad showed full screen content.');
      customAdEventCallback?.onAdShowedFullScreenContent?.();
    },
    // Called when the ad is closed by the user.
    onAdDismissedFullScreenContent: () => {
      console.log('Preloaded app open ad dismissed full screen content.');
      customAdEventCallback?.onAdDismissedFullScreenContent?.();
      ad.destroy();
    },
    // Called when presentation fails.
    onAdFailedToShowFullScreenContent: (error) => {
      console.error('Failed to show preloaded app open ad:', error);
      customAdEventCallback?.onAdFailedToShowFullScreenContent?.(error);
      ad.destroy();
    },
    // Called when an impression is recorded.
    onAdImpression: () => {
      console.log('Preloaded app open ad recorded an impression.');
      customAdEventCallback?.onAdImpression?.();
    },
    // Called when the user taps the ad.
    onAdClicked: () => {
      console.log('Preloaded app open ad was clicked.');
      customAdEventCallback?.onAdClicked?.();
    },
    // Called when the ad is estimated to have earned money.
    onAdPaid: (adValue) => {
      console.log(
        `Preloaded app open ad paid: ${adValue.amountMicros}` +
          ` ${adValue.currencyCode}`,
      );
      customAdEventCallback?.onAdPaid?.(adValue);
    },
  };

  ad.show();
}

Aby zwolnić pamięć i zasoby, wywołaj metodę ad.destroy w wywołaniach zwrotnych onAdDismissedFullScreenContent i onAdFailedToShowFullScreenContent, gdy użytkownik zamknie reklamę lub gdy nie uda się jej wyświetlić.

Przeczytaj informacje o odpowiedzi.

Aby sprawdzić szczegóły następnej wstępnie załadowanej reklamy bez usuwania jej z pamięci podręcznej, wywołaj metodę AppOpenAdPreloader.peekAdResponseInfo:

export function peekAppOpenAdResponseInfo(
  preloadId: string,
): ResponseInfo | null {
  const responseInfo = AppOpenAdPreloader.peekAdResponseInfo(preloadId);
  if (responseInfo) {
    console.log('Next preloaded app open ad response info:', responseInfo);
  }
  return responseInfo;
}

Zarządzanie reklamami wyświetlanymi przy otwarciu aplikacji za pomocą menedżera na poziomie aplikacji

Reklamy wyświetlane przy otwarciu aplikacji są wyświetlane globalnie podczas uruchamiania aplikacji i przechodzenia na pierwszy plan, dlatego zalecamy zarządzanie stanem cyklu życia modułu wstępnego wczytywania w menedżerze na poziomie aplikacji poza drzewem komponentów React.

Korzystanie z menedżera na poziomie aplikacji zapewnia kilka kluczowych korzyści:

  • Utrzymuje stan modułu wstępnego wczytywania niezależnie od nawigacji po poszczególnych ekranach i cyklu życia komponentu.
  • Scentralizowanie wywołań zwrotnych zdarzeń reklamowych, śledzenia stanu i czyszczenia w jednej współdzielonej instancji w aplikacji.
  • Kontroluje, kiedy nasłuchiwane są zdarzenia przełączenia aplikacji na pierwszy plan, zapobiegając powielaniu prezentacji po zamknięciu reklamy.

W tym przykładzie implementujemy menedżera na poziomie aplikacji za pomocą obiektu AppOpenAdPreloader:

export class AppOpenAdManager {
  private adUnitId: string;
  private preloadId: string;
  private appStateSubscription?: NativeEventSubscription;
  private startTimeoutId?: ReturnType<typeof setTimeout>;

  constructor(adUnitId: string, preloadId: string) {
    this.adUnitId = adUnitId;
    this.preloadId = preloadId;
  }

  start(): boolean {
    if (!AppOpenAdPreloader.getConfiguration(this.preloadId)) {
      AppOpenAdPreloader.start(
        this.preloadId,
        {
          request: {adUnitId: this.adUnitId},
          bufferSize: 2,
        },
        {
          onAdPreloaded: (event) => {
            console.log(`App open ad preloaded for ${event.preloadId}`);
          },
          onAdFailedToPreload: (error: LoadAdError) => {
            console.error('Failed to preload app open ad:', error.message);
          },
          onAdsExhausted: () => {
            console.log('App open ad buffer exhausted.');
          },
        },
      );
    }

    if (!this.appStateSubscription && !this.startTimeoutId) {
      // Delay attaching the listener to ensure native dismissal transitions complete
      this.startTimeoutId = setTimeout(() => {
        this.startTimeoutId = undefined;
        if (!this.appStateSubscription) {
          this.appStateSubscription = AppState.addEventListener(
            'change',
            (nextAppState: AppStateStatus) => {
              if (nextAppState === 'active') {
                this.showAdIfAvailable();
              }
            },
          );
        }
      }, APP_STATE_LISTENER_DELAY_MS);
    }

    return true;
  }

  pause(): void {
    if (this.startTimeoutId) {
      clearTimeout(this.startTimeoutId);
      this.startTimeoutId = undefined;
    }
    this.appStateSubscription?.remove();
    this.appStateSubscription = undefined;
  }

  stop(): void {
    this.pause();
    AppOpenAdPreloader.destroy(this.preloadId);
  }

  showAdIfAvailable() {
    if (!AppOpenAdPreloader.isAdAvailable(this.preloadId)) {
      console.log('App open ad is not preloaded or available right now.');
      return;
    }

    const ad = AppOpenAdPreloader.pollAd(this.preloadId);
    if (!ad) {
      return;
    }

    // Pause listener while presenting the ad
    this.pause();

    ad.adEventCallback = {
      onAdShowedFullScreenContent: () => {
        console.log('Preloaded app open ad showed full screen content.');
      },
      onAdDismissedFullScreenContent: () => {
        console.log('Preloaded app open ad dismissed full screen content.');
        ad.destroy();
        this.start();
      },
      onAdFailedToShowFullScreenContent: (error) => {
        console.error('Failed to show preloaded app open ad:', error);
        ad.destroy();
        this.start();
      },
    };

    ad.show();
  }
}

Nasłuchiwanie zdarzeń przełączenia aplikacji na pierwszy plan

Aby wyświetlać reklamy displayowe, gdy aplikacja wraca na pierwszy plan, zarejestruj detektor change w module AppState w komponencie głównym aplikacji, np. App.tsx. Sprawdź, kiedy stan zmieni się na active. Możesz na przykład wywołać metodę start w instancji menedżera reklam w komponencie App.tsx.

Wyświetlanie nakładek na reklamach lub stron docelowych, np. wyświetlanie reklam pełnoekranowych lub kliknięcie banera reklamowego, powoduje przeniesienie aplikacji do tła. Gdy użytkownik wróci do aplikacji, otrzyma ona nowe zdarzenie stanu active. Aby zapobiec niezamierzonemu wyświetlaniu reklamy lub pętli, w której po powrocie z reklamy wyświetla się reklama wyświetlana przy otwarciu aplikacji z pamięci podręcznej, wykonaj te czynności:

  1. Przed wyświetleniem reklamy pełnoekranowej usuń detektor zdarzeń AppState.
  2. Aby mieć pewność, że odtwarzanie zostanie wznowione, gdy użytkownik zamknie reklamę lub gdy reklama się nie wyświetli, dodaj ponownie detektor zdarzeń AppState w wywołaniach zwrotnych onAdDismissedFullScreenContent i onAdFailedToShowFullScreenContent.

Pełny przykład kontrolowania wstrzymywania i wznawiania detektorów zdarzeń na pierwszym planie znajdziesz w implementacji AppOpenAdManager.

Informacje o uruchomieniach „na zimno” i ekranach wczytywania

Zimny start ma miejsce, gdy aplikacja uruchamia się od zera, np. gdy użytkownik otwiera ją po raz pierwszy lub po tym, jak urządzenie zamknęło ją, aby zwolnić pamięć. Podczas uruchamiania „na zimno” nie masz wcześniej wczytanej reklamy wyświetlanej przy otwarciu aplikacji, którą można by wyświetlić.

Z powodu opóźnień w żądaniach reklamy użytkownicy mogą wejść w interakcję z aplikacją, zanim pojawi się reklama. Reklamy wyświetlane przy otwarciu aplikacji pokazuj podczas uruchamiania „na zimno” tylko na ekranie wczytywania, gdy wczytują się zasoby aplikacji. Jeśli zasoby zostaną wczytane i użytkownik dotrze do głównej treści, zanim reklama się wczyta, nie wyświetlaj reklamy.

Czyszczenie zasobów

Gdy wstępne wczytywanie nie jest już wymagane w przypadku ekranu lub identyfikatora jednostki reklamowej, np. gdy opuszczasz ekran, który wstępnie wczytuje reklamy, wywołaj metodę AppOpenAdPreloader.destroy, aby zwolnić zasoby wstępnego wczytywania i zapobiec przechowywaniu nieużywanych obiektów reklamowych w pamięci:

export function destroyAppOpenAdPreloader(preloadId: string) {
  AppOpenAdPreloader.destroy(preloadId);
}

Oprócz niszczenia kolejki wstępnego wczytywania pamiętaj o niszczeniu poszczególnych instancji reklam, gdy użytkownik odrzuci reklamę lub gdy nie uda się jej wyświetlić. Szczegółowe informacje znajdziesz w sekcji Sprawdzanie i wyświetlanie reklamy.

Zobacz pełny przykład

Poniższy przykładowy komponent rozpoczyna wstępne wczytywanie po zamontowaniu, śledzi liczbę dostępnych reklam i udostępnia elementy sterujące do wyświetlania wstępnie wczytanych reklam wyświetlanych przy otwarciu aplikacji:

export function AppOpenScreen() {
  const [numAdsAvailable, setNumAdsAvailable] = useState<number>(0);
  const [status, setStatus] = useState<string>('Preloader idle.');

  const refreshAdCount = () => {
    const count = AppOpenAdPreloader.getNumAdsAvailable(PRELOAD_ID);
    setNumAdsAvailable(count);
  };

  useEffect(() => {
    // Start preloading ads on component mount
    const started = startAppOpenAdPreloader(APP_OPEN_AD_UNIT_ID, PRELOAD_ID, {
      onAdPreloaded: () => {
        refreshAdCount();
        setStatus('App open ad preloaded into buffer.');
      },
      onAdFailedToPreload: (error) => {
        setStatus(`Failed to preload app open ad: ${error.message}`);
      },
      onAdsExhausted: () => {
        refreshAdCount();
        setStatus('Preload buffer exhausted for app open ads.');
      },
    });
    if (started) {
      setStatus('Preloader started.');
    }

    // Clean up preloader resources on component unmount
    return () => {
      destroyAppOpenAdPreloader(PRELOAD_ID);
    };
  }, []);

  const handleShowAd = () => {
    setStatus('Showing preloaded ad...');
    showPreloadedAppOpenAd(PRELOAD_ID, {
      onAdDismissedFullScreenContent: () => {
        setStatus('Ad dismissed.');
      },
      onAdFailedToShowFullScreenContent: (error) => {
        setStatus(`Failed to show preloaded ad: ${error.message}`);
      },
    });
    refreshAdCount();
  };

  return (
    <View style={styles.container}>
      <Text style={styles.title}>Preload App Open Ads</Text>
      <Text style={styles.status}>Status: {status}</Text>
      <Text style={styles.status}>Ads Available: {numAdsAvailable}</Text>
      <View style={styles.buttonGroup}>
        <Button
          title="Show Preloaded Ad"
          onPress={handleShowAd}
          disabled={numAdsAvailable === 0}
        />
      </View>
    </View>
  );
}

Zastąp te elementy:

  • APP_OPEN_AD_UNIT_ID identyfikatorem jednostki reklamowej.
  • PRELOAD_ID, podając identyfikator wstępnego ładowania.

Dalsze kroki

Po zintegrowaniu reklam wyświetlanych przy otwarciu aplikacji zapoznaj się z tymi tematami: