设置激励广告

激励广告会在用户与视频广告、试玩广告和调查问卷互动后，向其发放应用内商品。如需了解详情，请参阅激励广告单元概览。

为了消除展示延迟并确保在用户获得奖励时有广告可用，Google Mobile Ads SDK for React Native 使用广告预加载来管理后台加载、缓存和缓冲区补充。

本指南介绍了如何在 React Native 原生应用中植入激励广告。

前提条件

在继续操作之前，请确保满足以下条件：

Android

ca-app-pub-3940256099942544/5224354917

iOS 

ca-app-pub-3940256099942544/1712485313

了解广告预加载

Google Mobile Ads SDK for React Native 中的广告预加载功能可自动加载和缓存广告。

广告预加载具有以下优势：

  • 引用管理：在广告展示之前，保留对广告的引用。
  • 自动重新加载：从缓存中检索到广告后，加载新广告。
  • 代管式重试：在广告加载失败时加载新广告。
  • 过期处理：在广告过期前刷新广告。
  • 缓存优化：优化缓存顺序，以投放优先级最高的广告。

如需手动加载广告，请参阅加载单个激励广告。

开始预加载

如需开始预加载广告，请调用 RewardedAdPreloader.start 方法，并传递 preloadId 值、配置设置和事件回调，以监控缓冲区状态变化：

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

预加载 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 两个。

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

轮询并展示广告

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

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

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

export function showPreloadedRewardedAd(
  preloadId: string,
  onRewardEarned: (reward: Reward) => void,
  customAdEventCallback?: FullScreenAdEventCallback,
) {
  if (!RewardedAdPreloader.isAdAvailable(preloadId)) {
    console.log('No preloaded rewarded ad available right now.');
    return;
  }

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

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

  ad.show(onRewardEarned);
}

如需释放内存和资源，请在 onAdDismissedFullScreenContent 和 onAdFailedToShowFullScreenContent 回调中调用 ad.destroy 方法。

查看回答信息

如需检查下一个预加载广告的响应信息，而不从缓存中移除该广告，请调用 RewardedAdPreloader.peekAdResponseInfo 方法：

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

如果广告可用，peekAdResponseInfo 方法会返回一个 ResponseInfo 对象，其中包含有关已加载的广告来源和广告联盟适配器的信息。

可选：验证服务器端验证回调

如果您的应用需要在服务器端验证 (SSV) 回调中包含自定义验证参数（例如用户 ID 或自定义奖励元数据），请在调用 show 之前，在轮询的广告实例上设置 serverSideVerificationOptions 属性。

您设置的值会传递给 SSV 回调查询参数：

  • userId：传递给 user_id 查询参数，用于标识用户。
  • customData：传递给 custom_data 查询参数，以转发自定义元数据。

以下示例在展示广告之前，对激励广告对象设置 ServerSideVerificationOptions（customData 和 userId）：

export function setServerSideVerificationRewarded(ad: RewardedAd) {
  ad.serverSideVerificationOptions = {
    userId: 'user_123',
    customData: 'sample_custom_data',
  };
}

清理资源

如果您在会话的剩余时间内不再需要展示特定预加载 ID 的广告，请调用 RewardedAdPreloader.destroy 方法。此过程会停止针对该预加载 ID 的预加载，并从内存中释放未使用的预加载广告。

以下示例会停止预加载：

export function destroyRewardedAdPreloader(preloadId: string) {
  RewardedAdPreloader.destroy(preloadId);
}

在用户关闭广告或广告未能展示后，请销毁各个轮询的广告实例。如需了解详情，请参阅轮询和展示广告。

查看完整示例

以下示例组件会在装载时开始预加载，跟踪可用的广告数量，并提供用于展示预加载的激励广告的控件：

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

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

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

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

  const handleShowAd = () => {
    setReward(null);
    setStatus('Showing preloaded ad...');
    showPreloadedRewardedAd(
      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 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>
  );
}

替换以下内容：

  • 将 REWARDED_AD_UNIT_ID 替换为您的广告单元 ID。
  • 将 PRELOAD_ID 替换为您的预加载器 ID。

后续步骤

集成激励广告后，请探索以下主题：