Konfigurowanie reklam pełnoekranowych z nagrodą

Pełnoekranowe reklamy pełnoekranowe z nagrodą to format reklamy, który umożliwia oferowanie zakupów w aplikacji w zamian za obejrzenie reklam wyświetlanych między ekranami lub poziomami gry. W przeciwieństwie do reklam z nagrodą użytkownicy nie muszą wyrażać zgody na wyświetlenie reklamy. Więcej informacji znajdziesz w studiach przypadku AdMob i przeglądzie jednostek pełnoekranowych reklam z nagrodą (beta).

Aby wyeliminować opóźnienia w wyświetlaniu i zapewnić dostępność reklamy w momencie przejścia, Google Mobile Ads SDK for React Native używa wstępnego ładowania reklam do zarządzania ładowaniem w tle, buforowaniem i uzupełnianiem bufora.

Z tego przewodnika dowiesz się, jak zintegrować reklamy pełnoekranowe z nagrodą ze wstępnym ładowaniem reklam w aplikacji React Native.

Wymagania wstępne

Zanim przejdziesz dalej, wykonaj te czynności:

Android 

ca-app-pub-3940256099942544/5354046379

iOS 

ca-app-pub-3940256099942544/6978759866

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 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 wczytywać reklamy ręcznie, przeczytaj artykuł Wczytywanie pojedynczej reklamy pełnoekranowej z nagrodą.

Rozpocznij wstępne wczytywanie

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

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

preloadId to ciąg znaków, który jednoznacznie identyfikuje konfigurację wstępnego ładowania reklam. Jeśli używasz identyfikatora jednostki reklamowej w przypadku pojedynczej konfiguracji wstępnego wczytywania w aplikacji, użyj tego identyfikatora 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. Ten limit jest wspólny dla wszystkich formatów i identyfikatorów wstępnego wczytywania.
  • Zalecany bufor: 2 wstępnie załadowane reklamy na każdy identyfikator wstępnego ładowania.

Jeśli aplikacja osiągnie limit, żądania w tle dotyczące wstępnie załadowanych reklam zostaną wstrzymane do czasu pobrania istniejących reklam z pamięci podręcznej lub ich usunięcia. Wstępne wczytywanie jest też tymczasowo wstrzymywane, gdy na ekranie wyświetla się reklama pełnoekranowa.

Ankieta i wyświetlenie reklamy

Zanim wyświetlisz reklamę, sprawdź, czy jest ona dostępna, wywołując metodę RewardedInterstitialAdPreloader.isAdAvailable. Aby pobrać reklamę, wywołaj metodę RewardedInterstitialAdPreloader.pollAd.

Aby wyświetlić reklamę, wywołaj metodę show z wywołaniem zwrotnym onUserEarnedReward, które przyzna nagrodę, gdy użytkownik skończy oglądać reklamę. Aby śledzić zdarzenia związane z wyświetlaniem, takie jak zamknięcie reklamy lub błędy wyświetlania, ustaw właściwość adEventCallback w instancji reklamy przed wywołaniem metody show.

W tym przykładzie sprawdzamy dostępność reklamy i nasłuchujemy zdarzeń wyświetlania na pełnym ekranie, zanim wyświetlimy reklamę:

export function showPreloadedRewardedInterstitialAd(
  preloadId: string,
  onRewardEarned: (reward: Reward) => void,
  customAdEventCallback?: FullScreenAdEventCallback,
) {
  if (!RewardedInterstitialAdPreloader.isAdAvailable(preloadId)) {
    console.log('No preloaded rewarded interstitial ad available right now.');
    return;
  }

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

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

  ad.show(onRewardEarned);
}

Aby zwolnić pamięć i zasoby, wywołaj metodę ad.destroy w wywołaniach zwrotnych onAdDismissedFullScreenContent i onAdFailedToShowFullScreenContent.

Przeczytaj informacje o odpowiedzi.

Aby sprawdzić informacje o odpowiedzi na następną wstępnie załadowaną reklamę bez usuwania jej z pamięci podręcznej, wywołaj metodę RewardedInterstitialAdPreloader.peekAdResponseInfo:

export function peekRewardedInterstitialAdResponseInfo(
  preloadId: string,
): ResponseInfo | null {
  const responseInfo =
    RewardedInterstitialAdPreloader.peekAdResponseInfo(preloadId);
  if (responseInfo) {
    console.log(
      'Next preloaded rewarded interstitial ad response info:',
      responseInfo,
    );
  }
  return responseInfo;
}

Jeśli reklama jest dostępna, metoda peekAdResponseInfo zwraca obiekt ResponseInfo zawierający informacje o wczytanym źródle reklamy i kartach sieciowych.

Opcjonalnie: sprawdzanie poprawności wywołań zwrotnych SSV

Jeśli Twoja aplikacja wymaga niestandardowych parametrów weryfikacji, takich jak identyfikator użytkownika lub niestandardowe metadane nagrody, w wywołaniach zwrotnych weryfikacji po stronie serwera (SSV), ustaw właściwość serverSideVerificationOptions w instancji reklamy, zanim wywołasz metodę show.

Ustawione przez Ciebie wartości są przekazywane do parametrów zapytania wywołania zwrotnego SSV:

  • userId: przekazuje do parametru zapytania user_id, aby zidentyfikować użytkownika.
  • customData: przekazuje do parametru zapytania custom_data, aby przekazywać niestandardowe metadane.

W tym przykładzie ustawiamy ServerSideVerificationOptions (customData i userId) w obiekcie reklamy pełnoekranowej z nagrodą przed wyświetleniem reklamy:

export function setServerSideVerificationRewardedInterstitial(
  ad: RewardedInterstitialAd,
) {
  ad.serverSideVerificationOptions = {
    userId: 'user_123',
    customData: 'sample_custom_data',
  };
}

Czyszczenie zasobów

Jeśli nie musisz już wyświetlać reklam dla określonego identyfikatora wstępnego wczytywania przez resztę sesji, wywołaj metodę RewardedInterstitialAdPreloader.destroy. Ten proces zatrzymuje wstępne wczytywanie dla danego identyfikatora i zwalnia nieużywane wstępnie wczytane reklamy z pamięci.

Poniższy przykład zatrzymuje wstępne wczytywanie:

export function destroyRewardedInterstitialAdPreloader(preloadId: string) {
  RewardedInterstitialAdPreloader.destroy(preloadId);
}

Gdy użytkownik zamknie reklamę lub gdy nie uda się jej wyświetlić, zniszcz poszczególne instancje reklam, które zostały pobrane. Więcej informacji znajdziesz w artykule Sprawdzanie i wyświetlanie reklamy.

Zobacz pełny przykład

W tej sekcji znajdziesz szczegółowe instrukcje dotyczące wdrożenia wstępnego ładowania reklam.

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 pełnoekranowych z nagrodą:

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

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

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

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

  const handleShowAd = () => {
    setReward(null);
    setStatus('Showing preloaded ad...');
    showPreloadedRewardedInterstitialAd(
      PRELOAD_ID,
      (userReward) => {
        setReward(`${userReward.amount} ${userReward.type}`);
      },
      {
        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 Rewarded Interstitial Ads</Text>
      <Text style={styles.status}>Status: {status}</Text>
      <Text style={styles.status}>Ads Available: {numAdsAvailable}</Text>
      {reward && <Text style={styles.rewardText}>Earned: {reward}</Text>}
      <View style={styles.buttonGroup}>
        <Button
          title="Show Preloaded Ad"
          onPress={handleShowAd}
          disabled={numAdsAvailable === 0}
        />
      </View>
    </View>
  );
}

Dalsze kroki

Po zintegrowaniu reklam pełnoekranowych z nagrodą zapoznaj się z tymi tematami: