设置插页式激励广告

插页式激励广告是一种全屏广告格式，可让您针对在屏幕或游戏关卡之间展示的广告提供应用内商品。与激励广告不同，用户无需选择观看即可看到此类广告。如需了解详情，请参阅 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 最多在内存中保留 6 个预加载的广告。此限制适用于所有格式和预加载 ID。
  • 建议的缓冲量：每个预加载 ID 预加载两个广告。

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

轮询并展示广告

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

如需展示广告，请调用 show 方法，并使用 onUserEarnedReward 回调在用户看完广告后发放奖励。如需监听展示事件（例如广告关闭或展示失败），请在调用 show 方法之前，在广告实例上设置 adEventCallback 属性。

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

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 或自定义奖励元数据），请在调用 show 方法之前，在轮询的广告实例上设置 serverSideVerificationOptions 属性。

您设置的值会传递给 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>
  );
}

后续步骤

植入插页式激励广告后，请探索以下主题：