設定插頁式廣告

插頁式廣告會全螢幕顯示，通常出現在應用程式的轉換點，例如畫面切換時，或遊戲關卡間的暫停時間。使用者可以輕觸廣告前往到達網頁，也可以關閉廣告返回應用程式。詳情請參閱插頁式廣告指南和個案研究。

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

本指南說明如何在 React Native 應用程式中整合插頁式廣告。

必要條件

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

僅適用於搭載 Android 

ca-app-pub-3940256099942544/1033173712

iOS 

ca-app-pub-3940256099942544/4411468910

瞭解廣告預先載入

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

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

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

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

開始預先載入

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

export function startPreloader(
  adUnitId: string,
  preloadId: string,
  customPreloadCallback?: PreloadCallback,
): boolean {
  try {
    const started = InterstitialAdPreloader.start(
      preloadId,
      {
        request: {adUnitId},
        bufferSize: 2,
      },
      {
        // Called when an ad is preloaded into the buffer.
        onAdPreloaded: (metadata) => {
          console.log(`Interstitial ad preloaded for ${metadata.preloadId}`);
          customPreloadCallback?.onAdPreloaded?.(metadata);
        },
        // Called when an ad fails to preload.
        onAdFailedToPreload: (error: LoadAdError) => {
          console.error('Failed to preload interstitial ad:', error.message);
          customPreloadCallback?.onAdFailedToPreload?.(error);
        },
        // Called when all preloaded ads in the buffer have been shown.
        onAdsExhausted: () => {
          console.log('Preload buffer exhausted for interstitial ads.');
          customPreloadCallback?.onAdsExhausted?.();
        },
      },
    );
    return started;
  } catch (error) {
    console.error('Error starting interstitial ad preloader:', error);
    return false;
  }
}

預先載入 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 預先載入兩個廣告。

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

輪詢並顯示廣告

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

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

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

export function showPreloadedAd(
  preloadId: string,
  customAdEventCallback?: FullScreenAdEventCallback,
) {
  if (InterstitialAdPreloader.isAdAvailable(preloadId)) {
    const ad = InterstitialAdPreloader.pollAd(preloadId);
    if (ad) {
      ad.adEventCallback = {
        // Called when the ad is presented on screen.
        onAdShowedFullScreenContent: () => {
          console.log('Preloaded interstitial ad showed full screen content.');
          customAdEventCallback?.onAdShowedFullScreenContent?.();
        },
        // Called when the ad is closed by the user.
        onAdDismissedFullScreenContent: () => {
          console.log('Preloaded interstitial ad dismissed.');
          customAdEventCallback?.onAdDismissedFullScreenContent?.();
          ad.destroy();
        },
        // Called when presentation fails.
        onAdFailedToShowFullScreenContent: (error) => {
          console.error('Preloaded interstitial ad failed to show:', error);
          customAdEventCallback?.onAdFailedToShowFullScreenContent?.(error);
          ad.destroy();
        },
        // Called when an impression is recorded.
        onAdImpression: () => {
          console.log('Preloaded interstitial ad recorded an impression.');
          customAdEventCallback?.onAdImpression?.();
        },
        // Called when the user taps the ad.
        onAdClicked: () => {
          console.log('Preloaded interstitial ad was clicked.');
          customAdEventCallback?.onAdClicked?.();
        },
        // Called when the ad is estimated to have earned money.
        onAdPaid: (adValue) => {
          console.log(
            `Preloaded interstitial ad paid: ${adValue.amountMicros}` +
              ` ${adValue.currencyCode}`,
          );
          customAdEventCallback?.onAdPaid?.(adValue);
        },
      };
      ad.show();
    }
  } else {
    console.log('No preloaded interstitial ad available in buffer.');
  }
}

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

讀取回應資訊

如要檢查下一個預先載入廣告的回應資訊，而不從快取中移除廣告，請呼叫 InterstitialAdPreloader.peekAdResponseInfo 方法：

export function peekPreloadedAdResponseInfo(preloadId: string) {
  if (InterstitialAdPreloader.isAdAvailable(preloadId)) {
    const responseInfo = InterstitialAdPreloader.peekAdResponseInfo(preloadId);
    if (responseInfo) {
      console.log('Next preloaded ad response info:', responseInfo);
    }
  }
}

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

清除所用資源

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

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

export function destroyPreloader(preloadId: string) {
  InterstitialAdPreloader.destroy(preloadId);
}

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

查看完整範例

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

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

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

  useEffect(() => {
    // Start preloading interstitial ads on component mount
    startPreloader(INTERSTITIAL_AD_UNIT_ID, PRELOAD_ID, {
      onAdPreloaded: () => {
        refreshAdCount();
        setStatus('Ad preloaded and ready!');
      },
      onAdFailedToPreload: (error) => {
        setStatus(`Preload failed: ${error.message}`);
      },
      onAdsExhausted: () => {
        refreshAdCount();
        setStatus('Preload buffer exhausted.');
      },
    });
    setStatus('Preloader started.');

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

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

  return (
    <View style={styles.container}>
      <Text style={styles.title}>Preload Interstitial 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={handleShow}
          disabled={numAdsAvailable === 0}
        />
      </View>
    </View>
  );
}

更改下列內容：

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

後續步驟

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