載入單一應用程式開啟頁面廣告

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

應用程式開啟頁面廣告指南和最佳做法。

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

必要條件

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

僅適用於搭載 Android 

ca-app-pub-3940256099942544/9257395921

iOS 

ca-app-pub-3940256099942544/5575463023

載入廣告

如要載入應用程式開啟頁面廣告，請呼叫 load 方法。

以下範例會在成功時載入應用程式開啟頁面廣告，失敗時則記錄錯誤：

export async function loadAppOpenAd(
  adUnitId: string,
): Promise<AppOpenAd | null> {
  try {
    const ad = await AppOpenAd.load({adUnitId});
    return ad;
  } catch (error) {
    const loadError = error as LoadAdError;
    console.error('Failed to load app open ad:', loadError.message);
    return null;
  }
}

監聽廣告事件

顯示廣告前，請在載入的 AppOpenAd 執行個體上設定 adEventCallback 事件監聽器。這個事件監聽器會接收廣告生命週期事件的回呼，例如廣告顯示在畫面上，或使用者輕觸廣告。如要查看可用的回呼，請參閱 AdEventCallback。

以下範例設定了回呼，用於監聽廣告事件：

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

這個範例也會在使用者關閉廣告或廣告無法顯示時，使用 destroy 方法。這個程序會釋出廣告使用的資源。

顯示廣告

如要顯示應用程式開啟頁面廣告，請呼叫 show 方法：

export function showAppOpenAd(ad: AppOpenAd) {
  ad.show();
}

使用應用程式層級管理工具管理廣告

建議您在 React 元件樹狀結構外的應用程式層級管理工具中，管理應用程式開啟頁面廣告。由於應用程式開啟頁面廣告會在使用者開啟或返回應用程式時，在全域顯示，因此應用程式層級管理工具會將廣告與使用者介面分開。

以下範例會建立 SingleLoadAppOpenAdManager 例項，用於載入廣告、監聽廣告事件，以及檢查廣告可用性：

export class SingleLoadAppOpenAdManager {
  private ad: AppOpenAd | null = null;
  private loadTime = 0;
  private isShowingAd = false;

  async loadAd(adUnitId: string) {
    // Avoid re-loading if an ad is already loaded or showing.
    if (this.ad) {
      return;
    }
    try {
      this.ad = await AppOpenAd.load({adUnitId});
      this.loadTime = Date.now();
      this.ad.adEventCallback = {
        onAdDismissedFullScreenContent: () => {
          this.ad?.destroy();
          this.ad = null;
          this.isShowingAd = false;
          // Preload the next ad for future foreground transitions.
          this.loadAd(adUnitId);
        },
        onAdFailedToShowFullScreenContent: () => {
          // An ad object that fails to present is consumed and cannot be reused.
          // Clean up native resources and preload a new ad for future events.
          this.ad?.destroy();
          this.ad = null;
          this.isShowingAd = false;
          this.loadAd(adUnitId);
        },
      };
    } catch (error) {
      console.error('Failed to load app open ad:', error);
    }
  }

  showAdIfAvailable() {
    if (!this.ad || !this.isAdAvailable()) {
      console.warn(
        'App open ad cannot be shown: ad is not loaded or has expired.',
      );
      return;
    }
    if (this.isShowingAd) {
      console.warn('App open ad cannot be shown: an ad is already displaying.');
      return;
    }

    this.ad.show();
    this.isShowingAd = true;
  }

  isAdAvailable(): boolean {
    // App Open ads expire after 4 hours per Google Mobile Ads policy.
    const FOUR_HOURS_IN_MS = 4 * 60 * 60 * 1000;
    return this.ad !== null && Date.now() - this.loadTime < FOUR_HOURS_IN_MS;
  }
}

應用程式層級管理員可協助您執行下列操作：

  • 廣告狀態應與畫面導覽和元件生命週期分開。
  • 追蹤原生執行緒事件的廣告顯示狀態。
  • 處理應用程式前景轉換，避免重複顯示廣告。
  • 在背景預先載入廣告，以便在應用程式開啟時顯示。
  • 請留意四小時的廣告效期限制，避免顯示逾時廣告。
  • 結合載入、顯示和清理廣告資源。

監聽應用程式前景事件

如要在應用程式返回前景時顯示廣告，請使用 AppState 模組，在應用程式根目錄 (例如 App.tsx 檔案) 監聽應用程式狀態變更。請完成下列步驟：

  1. 為 'change' 事件註冊 AppState 監聽器。
  2. 當狀態轉換為 'active' 狀態時，請對廣告管理工具例項呼叫 showAdIfAvailable 方法。

以下範例會監聽應用程式前景事件，並在有廣告時顯示：

export function setupAppOpenAdForegroundListener(adManager: {
  showAdIfAvailable: () => void;
}): NativeEventSubscription {
  return AppState.addEventListener('change', (nextAppState: AppStateStatus) => {
    if (nextAppState === 'active') {
      adManager.showAdIfAvailable();
    }
  });
}

瞭解冷啟動和載入畫面

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

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

設定測試畫面

如要以互動方式測試廣告，或在特定畫面上顯示廣告，請在元件狀態中管理廣告例項。

以下範例說明如何使用 useEffect 清理掛鉤，將應用程式開啟頁面廣告整合至 React Native 元件。如果元件在廣告顯示前卸載，這個掛鉤會釋出原生資源。

export function AppOpenSingleLoadScreen() {
  const [ad, setAd] = useState<AppOpenAd | null>(null);
  const [isLoaded, setIsLoaded] = useState(false);
  const [status, setStatus] = useState<string>('Idle');

  useEffect(() => {
    return () => {
      ad?.destroy();
    };
  }, [ad]);

  const handleLoad = async () => {
    setStatus('Loading App Open ad...');
    const loadedAd = await loadAppOpenAd(APP_OPEN_AD_UNIT_ID);
    if (loadedAd) {
      registerAdEvents(loadedAd);
      const onDismiss =
        loadedAd.adEventCallback?.onAdDismissedFullScreenContent;
      loadedAd.adEventCallback = {
        ...loadedAd.adEventCallback,
        onAdDismissedFullScreenContent: () => {
          onDismiss?.();
          setStatus('Ad dismissed.');
        },
      };
      setAd((prevAd) => {
        prevAd?.destroy();
        return loadedAd;
      });
      setIsLoaded(true);
      setStatus('App Open ad loaded!');
    } else {
      setStatus('Failed to load App Open ad.');
    }
  };

  const handleShow = () => {
    if (ad) {
      showAppOpenAd(ad);
      setIsLoaded(false);
    }
  };

  return (
    <View style={styles.container}>
      <Text style={styles.title}>App Open Ad</Text>
      <Text style={styles.status}>Status: {status}</Text>
      <View style={styles.buttonGroup}>
        <Button title="Load Ad" onPress={handleLoad} />
        <View style={styles.spacerSmall} />
        <Button title="Show Ad" onPress={handleShow} disabled={!isLoaded} />
      </View>
    </View>
  );
}

後續步驟

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