設定插頁式獎勵廣告

插頁式獎勵廣告是一種全螢幕廣告格式，可在畫面或遊戲關卡之間顯示，並提供應用程式內商品。與獎勵廣告不同的是，使用者不需選擇觀看即可看到廣告。詳情請參閱「AdMob 個案研究」和「插頁式獎勵廣告單元總覽 (Beta 版)」。

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

本指南說明如何在 React Native 應用程式中，整合插頁式獎勵廣告和廣告預先載入功能。

必要條件

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

僅適用於搭載 Android 

ca-app-pub-3940256099942544/5354046379

iOS 

ca-app-pub-3940256099942544/6978759866

瞭解廣告預先載入

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

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

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

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

開始預先載入

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

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 是用來識別廣告預先載入設定的專屬字串。如果您在應用程式中，使用廣告單元 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 會對預先載入的廣告總數，強制執行應用程式層級的限制：

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

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

輪詢並顯示廣告

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

如要顯示廣告，請呼叫 show 方法，並使用 onUserEarnedReward 回呼，在使用者看完廣告後發放獎勵。如要監聽廣告關閉或顯示失敗等顯示事件，請先在廣告例項上設定 adEventCallback 屬性，再呼叫 show 方法。

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

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

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

讀取回應資訊

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

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

選用：驗證 SSV 回呼

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

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

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

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

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

清除所用資源

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

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

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

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

查看完整範例

本節將說明廣告預先載入的完整導入方式。

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

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

後續步驟

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