游戏内广告接入指南

最近更新：2026-08-11

通过 PlayNova 宿主 Bridge 接入 Banner、插屏与激励广告。游戏运行在 iframe 内，使用 postMessage 与宿主通信 — 请勿在游戏包内嵌入第三方广告 SDK。

变现方式

广告由宿主侧填充与计费，收益与已认证创作者分成（默认 创作者 70%）。游戏只负责请求 load/show；库存、频控、曝光/点击上报由宿主完成。

每条消息信封：

json

{ "source": "...", "type": "...", "payload": { } }

游戏必须设置 source 为 playnova-game
宿主回包 source 为 playnova-host

广告形式：

激励视频 — 玩家主动触发（复活、双倍奖励、免费道具）。仅在收到 ads.rewarded_completed 后发奖。
插屏 — 自然断点（通关/结束）。禁止在操作过程中打断。
Banner — 由宿主渲染条带；游戏只请求显示/隐藏。

placement	场景
`revive`	失败后继续
`double_reward`	关卡结束加成
`free_item` / `unlock`	道具或内容解锁
`level_complete` / `level_start` / `game_over` / `pause`	插屏时机
`banner_bottom` / `banner_top`	Banner 位

接入流程

在自然断点调用 ads.load_*（带 placement，可选 requestId）。
等待 ads.*_loaded（或处理 *_failed，无广告时继续游戏）。
用同一 requestId / placement 调用 ads.show_*。
激励广告仅在 ads.rewarded_completed 时改游戏状态；dismissed/failed 不得发奖。

Bridge 消息类型

规范 type 字符串定义在 playnova-web（ads-bridge）。游戏包请与下列取值严格一致。

游戏 → 宿主

type	用途
`ads.load_rewarded`	预加载激励库存
`ads.show_rewarded`	展示激励（仅 completed 后发奖）
`ads.load_interstitial`	预加载插屏
`ads.show_interstitial`	在断点展示插屏
`ads.show_banner`	请求显示宿主 Banner
`ads.hide_banner`	隐藏宿主 Banner
`ads.preload`	预加载多种格式
`ads.get_banner_height`	查询 Banner 高度以适配布局

宿主 → 游戏

type	用途
`ads.rewarded_loaded`	激励已就绪
`ads.rewarded_failed`	激励加载/展示失败
`ads.rewarded_completed`	激励观看完成 — 可发奖
`ads.rewarded_dismissed`	激励提前关闭 — 不得发奖
`ads.interstitial_loaded`	插屏已就绪
`ads.interstitial_failed`	插屏失败
`ads.interstitial_closed`	插屏已关闭
`ads.banner_shown`	Banner 已显示
`ads.banner_hidden`	Banner 已隐藏
`ads.banner_failed`	Banner 失败

可粘贴示例

复制到 index.html（或模块）中，将发奖逻辑替换为你的玩法。

function pnAds(type, payload) {
  parent.postMessage({ source: 'playnova-game', type, payload }, '*');
}
function onPnHost(handler) {
  window.addEventListener('message', (e) => {
    const d = e.data;
    if (!d || d.source !== 'playnova-host') return;
    handler(d);
  });
}
// 示例：复活流程
pnAds('ads.load_rewarded', { placement: 'revive' });
onPnHost((msg) => {
  if (msg.type === 'ads.rewarded_loaded') {
    pnAds('ads.show_rewarded', {
      requestId: msg.payload && msg.payload.requestId,
      placement: 'revive',
      reward: { type: 'life', amount: 1 },
    });
  }
  if (msg.type === 'ads.rewarded_completed') {
    // 仅在此处发奖
  }
});

生产规范

禁止自动点击、强制循环，或遮挡关闭/跳过控件。
未收到对应 requestId 的 ads.rewarded_completed 不得发奖。
无填充时优雅降级，不要卡住玩家。
尽量先 load 再 show，缩短触发时的等待。
包内禁止第三方广告 SDK、追踪器或恶意弹窗脚本。
插屏频控由宿主执行；短时间刷 show 可能被忽略。

常见问题

能否在 zip 内接入 AdMob / Unity Ads？

不能。需求由 PlayNova 宿主聚合。嵌入其他 SDK 将无法通过审核，也不符合 iframe 沙箱假设。

宿主没有回包怎么办？

将超时或 *_failed 视为无填充，继续游戏，避免无限转圈。

收益在哪里看？

广告上线后，曝光与收益会进入创作者数据分析；结算按入驻协议执行。

宿主 Bridge 已在游玩页上线。以上消息类型即为生产契约 — 请按此实现。

游戏内广告接入指南 ​

变现方式 ​

推荐广告位 ​

接入流程 ​

Bridge 消息类型 ​

游戏 → 宿主 ​

宿主 → 游戏 ​

可粘贴示例 ​

生产规范 ​

常见问题 ​

能否在 zip 内接入 AdMob / Unity Ads？ ​

宿主没有回包怎么办？ ​

收益在哪里看？ ​