类型	用途	用户主动?	暂停游戏?
`INTERSTITIAL`	关卡之间的全屏广告	否	是
`REWARD`	复活、双倍金币等	是(用户主动点击)	是
`BANNER`	顶部/底部常驻横条	否	否

FRVR.ads.show(FRVR.ads.AdType.INTERSTITIAL).then(result => {
  // result 是以下之一:
  //   FRVR.ads.AdShowResult.NOT_DISPLAYED  —— 没有就绪的广告,或被节流
  //   FRVR.ads.AdShowResult.DELIVERED      —— 已展示,用户已关闭
  //   FRVR.ads.AdShowResult.COMPLETED      —— (激励)看完了
});

激励流里只有 COMPLETED 才发奖励。用 DELIVERED 来判断玩家主动跳过 —— 广告确实展示了,但在结束前被关掉,因此不该发奖励。promise 被 reject(或任何其他结果)则表示广告根本没能展示:

FRVR.ads.show(FRVR.ads.AdType.REWARD).then((result) => {
  if (result === FRVR.ads.AdShowResult.COMPLETED) {
    giveReward();
  } else if (result === FRVR.ads.AdShowResult.DELIVERED) {
    showAdSkipped();   // 用户跳过 —— 不发奖励
  } else {
    showAdError();     // 没有就绪的广告 / 无法展示
  }
}).catch(() => {
  showAdError();
});

按就绪状态控制 UI

最糟的是「看广告」按钮点了没反应。展示前先用 isReady 检查一下:

if (FRVR.ads.isReady(FRVR.ads.AdType.REWARD)) {
  showWatchAdButton();
}

isSupported(type) 告诉你是否有任何 provider 能处理该类型(用来在没有横幅网络的平台上隐藏横幅按钮很方便)。

横幅

横幅会一直显示,直到你主动隐藏:

FRVR.ads.show(FRVR.ads.AdType.BANNER);
// 之后:
FRVR.ads.hide(FRVR.ads.AdType.BANNER);

节流(以及为什么 `NOT_DISPLAYED` 是默认状态)

插屏开箱就有节流 —— SDK 强制两次插屏之间有最小间隔(默认约 5 分钟),且会拒绝在会话开始的前约 100 秒内展示插屏。在这个窗口内请求插屏会直接 resolve 成 AdShowResult.NOT_DISPLAYED,不会调用任何 provider。这是预期行为,不是接入 bug。

测试或调频率时可以覆盖:

FRVR.config.ads = {
  throttling: {
    maxfrequency: 60000,   // 两次插屏之间至少 60 秒(毫秒)。0 表示禁用。
    initTimeBlock: 0,      // init 之后的全屏蔽窗口(毫秒)。0 表示禁用。
    forceFirstAd: true,    // 立即放行第一条插屏
  },
};

REWARD 与 BANNER 不可节流 —— 始终直达 provider。

生命周期

全屏广告打开时会自动触发 onSuspend → onAudioSuspend,关闭时触发对应的 …Resume。你不用手动暂停游戏 —— 把这些回调实现好就行(它们是必填的)。

监听广告展示

const unsubscribe = FRVR.ads.onAdShown(({ type, providerId }) => {
  analytics.tag('ad_shown', { type, providerId });
});

getAdShownCount() 按类型返回展示次数,适合给生命周期内总曝光做上限。

现在就试

下面这个 demo 走 dev 渠道,自带一个假的 provider。我们还传了 throttling: { maxfrequency: 0, forceFirstAd: true },这样你可以连点而不会撞上默认的 5 分钟冷却。dev 这个 provider 会弹一个浏览器 confirm() 对话框 —— 点确定模拟「广告完成」,取消模拟「跳过/关闭」。

广告:插屏、激励、横幅

loading SDK…

插屏

激励

横幅

API 摘要

方法	作用
`show(type)`	展示一条广告。返回 promise,resolve 成 `AdShowResult`。
`hide(type)`	隐藏常驻广告(通常是横幅)。
`isReady(type)`	当前是否有 provider 就绪?
`isSupported(type)`	当前渠道是否支持该广告类型?
`onAdShown(fn)`	订阅曝光。返回反订阅函数。
`getAdShownCount()`	自启动以来按类型的曝光计数。
`setUserConsent(bool)`	把更新后的同意状态传给各 provider。