设置插页式广告

插页式广告是全屏广告，会在应用中的过渡点（例如，屏幕之间或游戏关卡之间的暂停时段）展示。用户可以点按广告前往其目标页面，也可以关闭广告回到应用界面。如需了解详情，请参阅插页式广告指南和案例研究。

为了消除展示延迟并确保在发生转换时有广告可用，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 最多在内存中保留 6 个预加载的广告。此限制适用于所有格式和预加载 ID。
  • 建议的缓冲量：每个预加载 ID 预加载两个广告。

如果您的应用达到应用级限制，系统会暂停预加载广告的后台请求，直到从缓存中轮询现有广告或销毁现有广告。当全屏广告在屏幕上主动展示时，预加载也会暂时暂停。

轮询并展示广告

在展示广告之前，请调用 InterstitialAdPreloader.isAdAvailable 方法验证是否有广告可用。如需检索广告，请调用 InterstitialAdPreloader.pollAd 方法。

如需监听展示事件（例如广告关闭或展示失败），请在调用 show 方法之前，在广告实例上设置 adEventCallback 属性。

以下示例会检查广告是否可用，并在展示广告之前监听全屏展示事件：

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。

后续步骤

集成插页式广告后，请探索以下主题：