設定獎勵廣告

獎勵廣告會在使用者與影片廣告、可試玩廣告和問卷調查互動後，提供應用程式內商品做為獎勵。詳情請參閱「獎勵廣告單元總覽」。

為消除顯示延遲，並確保使用者獲得獎勵時能看到廣告，Google Mobile Ads SDK for React Native會使用廣告預先載入功能，管理背景載入、快取和緩衝區補充。

本指南說明如何在 React Native 原生應用程式中整合獎勵廣告。

必要條件

請先完成下列事項，再繼續操作：

僅適用於搭載 Android 

ca-app-pub-3940256099942544/5224354917

iOS 

ca-app-pub-3940256099942544/1712485313

瞭解廣告預先載入

Google Mobile Ads SDK for React Native中的廣告預先載入功能會自動載入及快取廣告。

廣告預先載入有下列好處：

  • 參考資料管理：保留參考資料，直到廣告顯示為止。
  • 自動重新載入：從快取擷取廣告時，載入新廣告。
  • 代管重試：廣告載入失敗時，系統會載入新廣告。
  • 過期處理：在廣告過期前重新整理。
  • 快取最佳化：最佳化快取順序，放送優先順序最高的廣告。

如要手動載入廣告，請參閱「載入單一獎勵廣告」一文。

開始預先載入

如要開始預先載入廣告，請呼叫 RewardedAdPreloader.start 方法，並傳遞 preloadId 值、配置設定和事件回呼，以監控緩衝區狀態變化：

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;
}

預先載入 ID 是用於識別廣告預先載入設定的專屬字串。如果您在應用程式中，使用廣告單元 ID 進行單一預先載入設定，則可將該廣告單元 ID 做為預先載入 ID。如果應用程式需要為同一個廣告單元 ID 使用多個預先載入器，請為每個預先載入 ID 傳遞不同的字串。

應用程式從緩衝區輪詢預先載入的廣告時，Google Mobile Ads SDK for React Native 會在背景請求替代廣告，重新填滿緩衝區。如果緩衝區中沒有預先載入的廣告，Google Mobile Ads SDK for React Native 會叫用 onAdsExhausted。

預先載入快取限制

Google Mobile Ads SDK for React Native 會對所有廣告單元和預先載入 ID，強制執行應用程式層級的預先載入廣告總數上限：

  • 預設限制：Google 最多會在記憶體中保留六則預先載入的廣告。這項限制適用於所有格式和預先載入 ID。
  • 建議的緩衝區空間大小：每個預先載入 ID 兩個。

如果應用程式達到全應用程式上限，系統會暫停預先載入廣告的背景要求，直到現有廣告從快取中輪詢或刪除為止。全螢幕廣告在畫面上顯示時，預先載入也會暫時暫停。

輪詢並顯示廣告

顯示廣告前，請呼叫 RewardedAdPreloader.isAdAvailable 方法，確認廣告是否可用。如要擷取廣告，請呼叫 RewardedAdPreloader.pollAd 方法。

如要監聽廣告關閉或顯示失敗等廣告顯示事件，請先在廣告例項上設定 adEventCallback 屬性，再呼叫 show 方法：

以下範例會檢查廣告是否可用，並在顯示廣告前監聽顯示事件：

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);
}

如要釋出記憶體和資源，請在 onAdDismissedFullScreenContent 和 onAdFailedToShowFullScreenContent 回呼中呼叫 ad.destroy 方法。

讀取回應資訊

如要檢查下一個預先載入廣告的回應資訊，而不從快取中移除廣告，請呼叫 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;
}

如果有廣告，peekAdResponseInfo 方法會傳回 ResponseInfo 物件，內含已載入廣告來源和聯播網轉接程式的相關資訊。

選用：驗證伺服器端驗證回呼

如果應用程式需要在伺服器端驗證 (SSV) 回呼中加入自訂驗證參數 (例如使用者 ID 或自訂獎勵中繼資料)，請先在輪詢的廣告例項上設定 serverSideVerificationOptions 屬性，再呼叫 show。

您設定的值會傳遞至 SSV 回呼查詢參數：

  • userId：傳遞至 user_id 查詢參數，用於識別使用者。
  • customData：傳遞至 custom_data 查詢參數，以轉送自訂中繼資料。

以下範例會在顯示廣告前，於獎勵廣告物件上設定 ServerSideVerificationOptions (customData 和 userId)：

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

清除所用資源

如果工作階段剩餘時間內，您不再需要顯示特定預先載入 ID 的廣告，請呼叫 RewardedAdPreloader.destroy 方法。這個程序會停止預先載入該 ID 的廣告，並從記憶體中釋出未使用的預先載入廣告。

以下範例會停止預先載入：

export function destroyRewardedAdPreloader(preloadId: string) {
  RewardedAdPreloader.destroy(preloadId);
}

使用者關閉廣告或廣告無法顯示後，請刪除個別輪詢的廣告例項。詳情請參閱「輪詢並顯示廣告」。

查看完整範例

以下範例元件會在掛接時開始預先載入、追蹤可用的廣告數量，並提供控制項來顯示預先載入的獎勵廣告：

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>
  );
}

更改下列內容：

  • 將 REWARDED_AD_UNIT_ID 換成您的廣告單元 ID。
  • 將 PRELOAD_ID 換成您的預先載入器 ID。

後續步驟

整合獎勵廣告後，請參閱下列主題：