設定應用程式開啟頁面廣告

應用程式開啟頁面廣告會在使用者開啟或返回應用程式時顯示，且使用者隨時可以關閉。如要利用應用程式載入畫面賺取收益，請使用應用程式開啟頁面廣告。詳情請參閱「應用程式開啟頁面廣告指南和最佳做法」。

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

必要條件

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

僅適用於搭載 Android 

ca-app-pub-3940256099942544/9257395921

iOS 

ca-app-pub-3940256099942544/5575463023

瞭解廣告預先載入

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

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

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

如要手動載入廣告，請參閱「載入單一應用程式開啟頁面廣告」指南。

開始預先載入

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

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

preloadId 是用來識別廣告預先載入設定的專屬字串。如果 adUnitId 僅用於應用程式中的單一預先載入設定，您可以使用該廣告單元 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 的緩衝區空間設為 2。

如果應用程式達到全應用程式上限，系統會暫停預先載入廣告的背景要求，直到現有廣告經過輪詢並顯示或刪除為止。

輪詢並顯示廣告

如要檢查是否有可用的預先載入廣告，並擷取廣告例項，請呼叫 AppOpenAdPreloader.pollAd 方法。

如要監聽全螢幕顯示事件，請先在傳回的 AppOpenAd 執行個體的 adEventCallback 屬性上註冊回呼，再呼叫 show 方法：

export function showPreloadedAppOpenAd(
  preloadId: string,
  customAdEventCallback?: FullScreenAdEventCallback,
) {
  if (!AppOpenAdPreloader.isAdAvailable(preloadId)) {
    console.log('No preloaded app open ad available right now.');
    return;
  }

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

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

  ad.show();
}

如要釋出記憶體和資源，請在使用者關閉廣告或廣告無法顯示時，在 onAdDismissedFullScreenContent 和 onAdFailedToShowFullScreenContent 回呼中呼叫 ad.destroy 方法。

讀取回應資訊

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

export function peekAppOpenAdResponseInfo(
  preloadId: string,
): ResponseInfo | null {
  const responseInfo = AppOpenAdPreloader.peekAdResponseInfo(preloadId);
  if (responseInfo) {
    console.log('Next preloaded app open ad response info:', responseInfo);
  }
  return responseInfo;
}

使用應用程式層級管理工具管理應用程式開啟頁面廣告

由於應用程式開啟頁面廣告會在應用程式啟動和前景轉換期間，在全域顯示，因此建議您在 React 元件樹狀結構外的應用程式層級管理工具中，管理預先載入器的生命週期狀態。

使用應用程式層級管理員有幾項主要優點：

  • 讓預先載入器狀態不受個別畫面導覽和元件生命週期的影響。
  • 在應用程式中，將廣告事件回呼、狀態追蹤和清除作業集中在單一共用例項中。
  • 控管監聽前景事件的時間，避免在廣告關閉時重複顯示。

以下範例使用 AppOpenAdPreloader 物件實作應用程式層級管理工具：

export class AppOpenAdManager {
  private adUnitId: string;
  private preloadId: string;
  private appStateSubscription?: NativeEventSubscription;
  private startTimeoutId?: ReturnType<typeof setTimeout>;

  constructor(adUnitId: string, preloadId: string) {
    this.adUnitId = adUnitId;
    this.preloadId = preloadId;
  }

  start(): boolean {
    if (!AppOpenAdPreloader.getConfiguration(this.preloadId)) {
      AppOpenAdPreloader.start(
        this.preloadId,
        {
          request: {adUnitId: this.adUnitId},
          bufferSize: 2,
        },
        {
          onAdPreloaded: (event) => {
            console.log(`App open ad preloaded for ${event.preloadId}`);
          },
          onAdFailedToPreload: (error: LoadAdError) => {
            console.error('Failed to preload app open ad:', error.message);
          },
          onAdsExhausted: () => {
            console.log('App open ad buffer exhausted.');
          },
        },
      );
    }

    if (!this.appStateSubscription && !this.startTimeoutId) {
      // Delay attaching the listener to ensure native dismissal transitions complete
      this.startTimeoutId = setTimeout(() => {
        this.startTimeoutId = undefined;
        if (!this.appStateSubscription) {
          this.appStateSubscription = AppState.addEventListener(
            'change',
            (nextAppState: AppStateStatus) => {
              if (nextAppState === 'active') {
                this.showAdIfAvailable();
              }
            },
          );
        }
      }, APP_STATE_LISTENER_DELAY_MS);
    }

    return true;
  }

  pause(): void {
    if (this.startTimeoutId) {
      clearTimeout(this.startTimeoutId);
      this.startTimeoutId = undefined;
    }
    this.appStateSubscription?.remove();
    this.appStateSubscription = undefined;
  }

  stop(): void {
    this.pause();
    AppOpenAdPreloader.destroy(this.preloadId);
  }

  showAdIfAvailable() {
    if (!AppOpenAdPreloader.isAdAvailable(this.preloadId)) {
      console.log('App open ad is not preloaded or available right now.');
      return;
    }

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

    // Pause listener while presenting the ad
    this.pause();

    ad.adEventCallback = {
      onAdShowedFullScreenContent: () => {
        console.log('Preloaded app open ad showed full screen content.');
      },
      onAdDismissedFullScreenContent: () => {
        console.log('Preloaded app open ad dismissed full screen content.');
        ad.destroy();
        this.start();
      },
      onAdFailedToShowFullScreenContent: (error) => {
        console.error('Failed to show preloaded app open ad:', error);
        ad.destroy();
        this.start();
      },
    };

    ad.show();
  }
}

監聽應用程式前景事件

如要在應用程式返回前景時顯示廣告，請在應用程式根元件 (例如 App.tsx) 的 AppState 模組上註冊 change 監聽器。查看狀態何時轉換為 active。舉例來說，在 App.tsx 元件中，對廣告管理工具例項呼叫 start 方法。

顯示廣告附加資訊或到達網頁 (例如顯示全螢幕廣告或輕觸橫幅廣告)，會將應用程式推到背景。使用者返回應用程式時，應用程式會收到新的 active 狀態事件。為避免廣告意外顯示，或使用者關閉廣告後，系統又從快取中顯示應用程式開啟頁面廣告，請按照下列步驟操作：

  1. 顯示全螢幕廣告前，請先移除 AppState 事件監聽器。
  2. 為確保無論使用者關閉廣告或廣告無法顯示，系統都能恢復聆聽，請在 onAdDismissedFullScreenContent 和 onAdFailedToShowFullScreenContent 回呼中再次新增 AppState 事件監聽器。

如需控制前景事件監聽器暫停和恢復時機的完整範例，請參閱 AppOpenAdManager 實作。

瞭解冷啟動和載入畫面

冷啟動是指應用程式從頭開始啟動，例如使用者首次開啟應用程式，或裝置關閉應用程式以釋出記憶體後。冷啟動時，您沒有預先載入的應用程式開啟頁面廣告可顯示。

由於廣告請求延遲，使用者可能會在廣告顯示前與應用程式互動。冷啟動時，應用程式開啟頁面廣告只能在載入畫面中顯示，同時載入應用程式素材資源。如果素材資源已載入完成，且使用者在廣告載入前就進入主要內容，請勿顯示廣告。

清除所用資源

如果畫面或廣告單元 ID 不再需要預先載入 (例如離開預先載入廣告的畫面)，請呼叫 AppOpenAdPreloader.destroy 方法釋出預先載入器資源，避免未使用的廣告物件占用記憶體：

export function destroyAppOpenAdPreloader(preloadId: string) {
  AppOpenAdPreloader.destroy(preloadId);
}

除了刪除預先載入器佇列，當使用者關閉廣告或廣告無法顯示時，也請務必刪除個別輪詢的廣告例項。詳情請參閱「輪詢並顯示廣告」。

查看完整範例

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

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

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

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

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

  const handleShowAd = () => {
    setStatus('Showing preloaded ad...');
    showPreloadedAppOpenAd(PRELOAD_ID, {
      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 App Open 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={handleShowAd}
          disabled={numAdsAvailable === 0}
        />
      </View>
    </View>
  );
}

更改下列內容：

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

後續步驟

整合應用程式開啟頁面廣告後，請參閱下列主題：