Konfigurowanie reklam z nagrodą

Reklamy z nagrodą dają użytkownikom zakupy w aplikacji w zamian za interakcje z reklamami wideo i reklamami demonstracyjnymi gier oraz za wypełnianie ankiet. Więcej informacji znajdziesz w artykule Przegląd jednostek reklamowych z nagrodą.

Aby wyeliminować opóźnienia w wyświetlaniu i zapewnić dostępność reklamy, gdy użytkownik zdobędzie nagrodę, 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 z nagrodą w aplikacji React Native.

Wymagania wstępne

Zanim przejdziesz dalej, wykonaj te czynności:

Android 

ca-app-pub-3940256099942544/5224354917

iOS 

ca-app-pub-3940256099942544/1712485313

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

Rozpocznij wstępne wczytywanie

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

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

Identyfikator wstępnego ładowania to ciąg znaków, który jednoznacznie identyfikuje konfigurację wstępnego ładowania reklam. Jeśli używasz identyfikatora jednostki reklamowej w pojedynczej konfiguracji wstępnego wczytywania w aplikacji, możesz go użyć 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 onAdsExhausted.

Limity wstępnego buforowania

Google Mobile Ads SDK for React Native 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.
  • Zalecany rozmiar bufora: 2 na każdy identyfikator wstępnego wczytywania.

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ę RewardedAdPreloader.isAdAvailable. Aby pobrać reklamę, wywołaj metodę RewardedAdPreloader.pollAd.

Aby wykrywać zdarzenia związane z wyświetlaniem, takie jak zamknięcie reklamy lub błąd wyświetlania, przed wywołaniem metody show ustaw właściwość adEventCallback w instancji reklamy:

W tym przykładzie sprawdzana jest dostępność reklamy, a przed jej wyświetleniem następuje nasłuchiwanie zdarzeń prezentacji:

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

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

  ad.adEventCallback = {
    // Called when the ad is presented on screen.
    onAdShowedFullScreenContent: () => {
      console.log('Preloaded rewarded ad showed full screen content.');
      customAdEventCallback?.onAdShowedFullScreenContent?.();
    },
    // Called when the ad is closed by the user.
    onAdDismissedFullScreenContent: () => {
      console.log('Preloaded rewarded ad dismissed full screen content.');
      customAdEventCallback?.onAdDismissedFullScreenContent?.();
      ad.destroy();
    },
    // Called when presentation fails.
    onAdFailedToShowFullScreenContent: (error) => {
      console.error('Failed to show preloaded rewarded ad:', error);
      customAdEventCallback?.onAdFailedToShowFullScreenContent?.(error);
      ad.destroy();
    },
    // Called when an impression is recorded.
    onAdImpression: () => {
      console.log('Preloaded rewarded ad recorded an impression.');
      customAdEventCallback?.onAdImpression?.();
    },
    // Called when the user taps the ad.
    onAdClicked: () => {
      console.log('Preloaded rewarded ad was clicked.');
      customAdEventCallback?.onAdClicked?.();
    },
    // Called when the ad is estimated to have earned money.
    onAdPaid: (adValue) => {
      console.log(
        `Preloaded rewarded 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ę RewardedAdPreloader.peekAdResponseInfo:

export function peekRewardedAdResponseInfo(
  preloadId: string,
): ResponseInfo | null {
  const responseInfo = RewardedAdPreloader.peekAdResponseInfo(preloadId);
  if (responseInfo) {
    console.log('Next preloaded rewarded 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 wywołań zwrotnych weryfikacji po stronie serwera

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.

Poniższy przykład ustawia ServerSideVerificationOptions (customData i userId) w obiekcie reklamy z nagrodą przed wyświetleniem reklamy:

export function setServerSideVerificationRewarded(ad: RewardedAd) {
  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ę RewardedAdPreloader.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 destroyRewardedAdPreloader(preloadId: string) {
  RewardedAdPreloader.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 sekcji Odpytywanie 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 z nagrodą:

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

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

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

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

  const handleShowAd = () => {
    setReward(null);
    setStatus('Showing preloaded ad...');
    showPreloadedRewardedAd(
      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 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>
  );
}

Zastąp te elementy:

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

Dalsze kroki

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