遊戲內廣告接入指南

最近更新：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？ ​

宿主沒有回包怎麼辦？ ​

收益在哪裡看？ ​