Metamoa 3D 廣告 · 3D ads
概覽
Metamoa 3D 廣告將廣告主的 3D 模型、廣告建築、廣告角色放到網頁元宇宙空間內的廣告位上,只計算人們實際看到和做過的行為來收取廣告費,並把其中的份額分給空間經營者。作為廣告業與廣告代理業,我們接受從大企業到中小企業的投放。
- 空間經營者:在空間管理的收益化(/owner/revenue)中進行「登記廣告刊登」(確認條款、結算資訊、廣告位)→ 放入一行腳本和廣告位即可。
- 廣告主:在 /ads/manage 用 Metamoa 帳號登入 → 上傳 3D 模型(glb),或選擇廣告建築並放入圖片或材質,或為基本廣告角色選擇道具和廣告 → 自行選擇曝光空間或使用「推薦」→ 計費方式、預算、期間 → 審核後投放。
- 沒有模型時選擇「模型製作請求」,我們會為您製作。也可以直接提供您的模型。基本廣告角色不論金額多少都免費。
- 計費有四種:CPM(viewable 曝光)、CPA(模型點擊、品牌空間進入)、曝光時間(累計顯示時間)、空間固定合約(按期,獨占廣告位)。金額皆為(供貨價,未稅)。
- 廣告模型的大小可能會依空間由空間經營者或 Metamoa 調整。




4 種商品與計費
金額皆為供貨價,未稅。
| 商品 | billing | 計算內容 | 單價 |
|---|---|---|---|
| CPM(viewable 曝光) | cpm | viewable 曝光 1 次 = 模型在畫面內達一定比例以上,並連續顯示超過規定時間(分頁可見的狀態) | 每 1,000 次 viewable ₩8,000 |
| CPA · 模型點擊 | cpa | 點按或點擊廣告模型。點擊後若繼續進入品牌空間,只按進入計費 1 次 | 每 1 次點擊 ₩700 |
| CPA · 品牌空間進入 | cpa | 點按廣告進入品牌空間(brand_url)。透過伺服器轉址(/ads/go)計算,同一人、同一活動每天一次 | 每 1 次進入 ₩1,000 |
| 曝光時間 | time | viewable 曝光後廣告被看到的累計時間(僅在有輸入操作時,最多到每人每模型每日上限) | 每 1,000 秒 viewable ₩1,000 |
| 空間固定合約 | fixed | 按期(最長一個月)。在該期間獨占所簽約的廣告位(以廣告位為單位)。不保證曝光次數 | 見下方等級表 |
空間固定合約等級
等級依該廣告位所在空間最近 14 天乾淨的每日空間點擊中位數決定(不計營運者本人、資料中心網路與自動化瀏覽器;metamoa 的「進入」只計通過真人驗證的)。未達最低等級的空間,其廣告位不以空間固定合約販售,只接受成效型投放。合約期間為每週 7 天或每月 30 天其中之一。
| 等級 | 每日空間點擊 | 每週(廣告位 1 個) | 每月(廣告位 1 個) |
|---|---|---|---|
| S | 1,000 以上 | ₩50,000 | ₩180,000 |
| A | 300~999 | ₩15,000 | ₩50,000 |
| B | 100~299 | ₩5,000 | ₩18,000 |
- 最低投放:媒體費 ₩10,000(供貨價,未稅),不含模型製作費。成效型以預算計,空間固定合約以合約金額合計計。
- 成效型(CPM、CPA、曝光時間)只按實際計算的量計費,花費金額達到預算(budget_won)後該活動不再投放。
- CPM 合約最多只接受所選廣告位預估 viewable 曝光(每日空間點擊 × 0.7 × 天數)的 70%(409 over_inventory)。
- CPA 與曝光時間型不會被擋下,但若預算大於預估花費,/ads/manage 會在申請前提醒:在相同的預估 viewable 曝光上,CPA 乘以點擊率基準 2% × 點擊與進入單價中較高者,曝光時間乘以每人每日 60 秒(GET /api/ads/options 的 spend_estimate)。
- 簽有空間固定合約的廣告位在該期間只投放該活動,同一廣告位、期間重疊的固定合約不再受理(409 slot_taken)。廣告位在審核核准時鎖定:待審核的申請不占用廣告位,先獲核准的合約優先。若有模型未顯示的日子,或流量下降超過 30%,將以按日退款或延長期間補償。
- 計費與等級以 Metamoa 實測報告(viewable 曝光、點擊、進入、顯示時間、空間點擊)為準。
統計公式
日期以韓國時間按日計(ad_daily)。金額為捨去韓元以下的供貨價。觸發規則的事件不計入,並依原因另行統計(ad_excluded)。
- viewable 曝光 imps = 通過全部規則的
imp事件數 - 點擊 clicks = 通過的
click數,進入 enters = 通過的進入(/ads/go)數,converted = 點擊後用同一權杖進入的數量 - 顯示時間 view_ms = 通過的
time事件 ms 總和(僅限曝光已計入的權杖,每個事件最多 15,000ms,最多到每人每模型每日上限) - CPM 金額 = floor(imps × cpm_won ÷ 1,000)
- CPA 金額 = (clicks − converted) × click_won + enters × enter_won
- 曝光時間金額 = floor(view_ms ÷ 1,000 × time_1000s_won ÷ 1,000)
- 空間固定合約金額 = 每個簽約廣告位等級單價的總和。只統計期間的一部分時,每個廣告位為 floor(單價 × 該期間內的合約天數 ÷ 合約天數)
- 空間經營者分潤 = floor(各空間金額 × 該空間的空間經營者等級比例(%) ÷ 100)。金額是扣除無效流量後的媒體供貨價,模型與空間製作費不分潤。等級見下方「空間經營者收益分潤等級」。
空間經營者收益分潤等級
廣告收益(各空間的廣告媒體金額,扣除無效流量後的供貨價)由空間經營者與 Metamoa 依等級比例分配。2026年11月11日起施行。優先登記說明:https://metamoa.com/ads/partners
| 等級 | 對象 | 空間經營者 : Metamoa |
|---|---|---|
| 白金 | 先到先得第 1~10 位空間經營者 | 9:1 |
| 黃金 | 第 11~100 位空間經營者(90 名) | 8:2 |
| 白銀 | 之後的空間經營者 | 7:3 |
| 青銅 | 自 2027年1月1日起新簽約的空間經營者 | 6:4 |
今後可能依廣告成效調整比例。
- 空間經營者 = 在 Metamoa 登記空間並登入空間管理的擁有者帳號。順序依在空間管理中首次開啟「同意刊登廣告」的時間先後,由伺服器逐一編號。
- 等級一經確定即維持不變,同一空間經營者的其他空間也是同一等級。
- 自 2027年1月1日 0 時(韓國時間)起新簽約的空間經營者,不論順序皆為青銅。
- 我的等級與比例:空間管理「3D 廣告」欄,GET /api/space/{id}/ads 的 partner。剩餘名額:GET /api/ads/partners 的 seats。
- 目前剩餘名額:白金 0/10 · 黃金 80/90
確認條款與同意刊登廣告
使用條款中已加入廣告刊登條款(第 4 條之 4)。要接收廣告,空間經營者需在空間管理收益化的「登記廣告刊登」中一次完成兩件事。
- 確認條款:在空間管理(/owner/revenue?id=<空間 id>)「登記廣告刊登」第 1 步勾選條款確認。只能在空間管理畫面操作(用空間金鑰為 403 owner_page_only)。
- 同意刊登廣告:與條款確認一起開啟,之後在同一畫面依空間開啟或關閉。開啟時需要結算資訊的類型與聯絡方式(沒有則 409 payout_info_required)。開啟後才會顯示該空間的廣告 API(一行腳本、廣告金鑰),關閉後立即停止投放(serve 403 ads_off)。
同意紀錄:空間、誰(登入該空間管理的空間經營者電子郵件的雜湊)、何時、哪個條款版本(terms.html 的 data-ads-version)、開啟/關閉,皆累積保存不刪除(ad_consents)。
未確認條款或關閉同意刊登廣告的空間,以及未列入目錄的空間,不投放廣告。
廣告位(插槽)
空間經營者自行決定在自己的元宇宙中廣告擺在哪裡。廣告主以廣告位為單位選擇或接受推薦,空間固定合約也以廣告位為單位簽訂。廣告位清單可在空間管理畫面查看與開關。
| 欄位 | 格式 | 意義 |
|---|---|---|
| name | 1~40 個字元 | 空間內不重複的名稱 |
| kind | floor · wall · air · character | 地面模型 · 牆面招牌 · 空中橫幅 · 站立或走動的廣告角色 |
| position | [x, y, z] 公尺 | 廣告位方框底面中心的位置(空間座標) |
| rotation | [x, y, z] 度(-360~360) | 廣告位的旋轉。預設 [0, 0, 0] |
| size | [寬, 高, 深] 公尺(0.1~200) | 放廣告的方框。廣告會依此方框放大或縮小 |
| scale | [最小, 最大] 倍(0.05~20) | 各空間的尺寸倍率:配合方框時,只在廣告原始尺寸的此倍率範圍內放大縮小。預設 [0.25, 4] |
| roam | 0~50 公尺 | character 廣告位:角色走動的半徑(0 表示站立) |
| industries | 產業 id 清單 | 此廣告位接受的產業。留空則接受所有產業 |
| enabled | true · false | 關閉後此廣告位不投放廣告 |
廣告模型的大小可能會依空間由空間經營者或 Metamoa 調整。
角色廣告只投放到 character 廣告位,模型與建築廣告只投放到 floor、wall、air 廣告位。
用 SDK(公開廣告金鑰)只能建立新廣告位,這樣建立的廣告位為關閉狀態,需空間經營者在空間管理中確認並開啟後才會投放廣告。既有的廣告位(同名)SDK 無法修改,會原樣回傳。關閉狀態的 SDK 廣告位每個空間最多 5 個,與空間經營者廣告位 30 個分開計算。一個 IP 群組每天最多可建立 20 個,空間經營者在 7 天內從未開啟的 SDK 廣告位會被刪除(曾開啟過的、活動正在使用的不會刪除)。開啟後計入空間經營者廣告位 30 個之內。修改廣告位的方框、類型、產業以及開關,只能用空間管理登入或空間金鑰。
產業 id:game(遊戲)· fashion(時尚·美妝)· food(餐飲)· tech(IT·電子)· finance(金融)· edu(教育)· travel(旅遊·休閒)· culture(文化·娛樂)· auto(汽車)· public(公共·非營利)· etc(其他)
每個空間最多 30 個廣告位。廣告位 API 使用空間金鑰(mm_live_)或空間管理登入:
GET https://metamoa.com/api/space/{space_id}/ads/slots
POST https://metamoa.com/api/space/{space_id}/ads/slots {"name":"plaza-front","kind":"floor","position":[0,0,-8],"rotation":[0,90,0],"size":[4,4,4],"scale":[0.5,2],"industries":["game","food"]}
POST https://metamoa.com/api/space/{space_id}/ads/slots {"name":"gate-greeter","kind":"character","position":[3,0,-4],"size":[1.2,2.2,1.2],"roam":3}
PATCH https://metamoa.com/api/space/{space_id}/ads/slots/{slot_id} {"enabled": false, "scale": [0.5, 1.5]}
DELETE https://metamoa.com/api/space/{space_id}/ads/slots/{slot_id}空間經營者:串接步驟
- 在空間管理收益化(
https://metamoa.com/owner/revenue?id=<空間 id>)的「登記廣告刊登」中勾選條款確認並開始廣告。 - 把同一畫面「廣告 API」欄的一行腳本放到空間頁面 <head> 或 <body> 結尾。廣告金鑰(mm_adpub_)可以公開(不要放入空間金鑰 mm_live_)。
- three.js 空間在場景建立後呼叫 attach 與 slot。廣告位第一次呼叫時以關閉狀態登記。在空間管理「廣告位」中開啟後即開始投放(也可以用廣告位 API 一開始就以開啟狀態建立)。
- 廣告顯示出來就完成了。viewable 曝光、點擊、顯示時間由 SDK 自動傳送,品牌空間進入則是點按廣告時 SDK 開啟 /ads/go 由伺服器計算。
- 在空間管理的「廣告位」中開關廣告位,查看 30 天統計(規則套用前後)與分潤(GET /api/space/{space_id}/ads/stats)。
<script src="https://metamoa.com/ads/sdk.js" data-space="{space_id}" data-key="{mm_adpub_…}" async></script>
import * as THREE from 'three';
import { GLTFLoader } from 'three/addons/loaders/GLTFLoader.js';
// after your scene, camera and renderer exist:
(window.metamoaAdsReady = window.metamoaAdsReady || []).push((ads) => {
ads.attach({ THREE, GLTFLoader, scene, camera, renderer });
ads.slot({ name: 'plaza-front', kind: 'floor', position: [0, 0, -8], rotation: [0, 0, 0], size: [4, 4, 4] });
ads.slot({ name: 'north-wall', kind: 'wall', position: [0, 3, -15], size: [6, 3.4, 0.4] });
ads.slot({ name: 'gate-greeter', kind: 'character', position: [3, 0, -4], size: [1.2, 2.2, 1.2], roam: 3 });
});
非 three.js 引擎(Babylon.js、PlayCanvas、Unity WebGL 等)以 serve 取得廣告後自行繪製並傳送事件:ads.serve(name) → { ad },ads.report(name, event)。進入時在新視窗或同一視窗開啟 ad.enter_url 即可。規格見下方「事件規格」。
SDK 的計算方式
- viewable 曝光:模型的規定比例以上在攝影機畫面內,畫面上的大小達規定面積以上,並在分頁可見期間持續超過規定時間,就傳送曝光 1 次(每個 serve 權杖一次)。
- 顯示時間:曝光後,在廣告符合上述條件可見期間,每 5 秒累計傳送一次,同時傳送期間的攝影機與指標輸入次數(分頁隱藏時停止)。
- serve 回應帶有 vid 時,將其保存在該瀏覽器,從下一次 serve 起一併傳送(GET /ads/v1/serve?…&vid=)。只有伺服器為該網路簽署的 vid 才會被讀取。伺服器把 vid 與連線 IP 群組合併,將此人簽署寫入權杖。曝光要在 serve 後約 2 秒才開始計入。
- 點擊:點按或點擊廣告時傳送
click,若廣告有品牌空間,則在新視窗開啟 enter_url(/ads/go)。伺服器計算進入並轉送到品牌空間。 - 門:若有 ad.door,走進門時在新視窗開啟一次 enter_url。再次開啟的條件見下方「從門進入」。
- 瀏覽器 id(vid)由伺服器提供,SDK 保存在 localStorage,只用於重複限制。不傳送姓名、聯絡方式等個人資訊。
- 廣告每 30 分鐘重新取得一次(新權杖)。character 廣告位的角色在 roam 半徑內慢慢走動。
從門進入
可以為廣告建築或自己的 3D 模型加一扇門。這是門,不是傳送門:人走進門時,目前的空間維持不變,在新視窗(新分頁)開啟品牌空間。在活動的 creative 中加入 "door": true(僅限 kind 為 model 或 building),且需要 brand_url(沒有則 400 invalid,fields brand_url)。serve 的 ad 中會帶有 door。
"creative": { "kind": "building", "building_id": "bld-corner-shop", "mode": "image", "images": { … }, "door": true }
serve → "ad": { …, "enter_url": "https://metamoa.com/ads/go?t=<serve 토큰>", "door": { "node": "door", "enter_m": 1.2, "exit_m": 3 } }
門不會反覆開啟的規則(務必遵守)
- 走到門前 1.2m 以內時,在新視窗開啟一次品牌空間(enter_url 加 &via=door)。
- 關閉新開的視窗回來後,即使在門內或門附近稍微移動,門也不會再次開啟。
- 只有走到離門超過 3m 的地方再回來,才會再次開啟(進入距離 1.2m < 離開距離 3m)。
- 分頁隱藏或視窗沒有焦點時不會開啟,回來後也必須先離開門的區域一次。開啟頁面時已站在門內也不會開啟。
- 點按或點擊建築開啟的方式與以往相同(每次點擊)。門的規則只適用於走進去的情況。
- 若瀏覽器封鎖新視窗,畫面下方會出現「開啟 <品牌>」按鈕。點按該按鈕才會開啟(不點按而離開門時按鈕消失)。
門的位置:glb 中有名為 door 的節點就用該節點,沒有則由 SDK 在廣告正面(+Z)中間的地面畫一扇預設門。距離是走動角色到門前的地面距離。請傳給 attach 一個 walker(走動角色的 Object3D 或回傳 {x, y, z} 的函式)。沒有時以攝影機位置測量。
ads.attach({ THREE, GLTFLoader, scene, camera, renderer, walker: player }); // player: the walking character (Object3D)
用非 three.js 引擎自行繪製 ad.door 的空間也必須同樣遵守上述規則:開啟一次後,在走出 exit_m 之前;分頁隱藏後回來,在離開門的區域一次之前,都不再開啟。
避免進進出出耗盡預算
- 從門進入的計費與 CPA 進入 1 次單價相同(單價與最低投放不變)。
- 同一人(伺服器提供的瀏覽器 id + 網路位址群組)、同一活動的進入,每 24 小時只計一次,30 天內最多 3 次。同一網路位址群組每個活動、每個空間每天最多 3 次。
- 超出的進入仍會轉送到品牌空間,但不計費,只做紀錄(排除原因 repeat_limit)。以伺服器的事件紀錄(僅雜湊)再次核對,伺服器重新啟動也不會遺忘。
- 同一 serve 權杖的進入只計一次,且只計算曝光已先被計入的權杖(沿用機器人與作弊檢測規則)。
機器人與作弊檢測規則
事件在伺服器上依序經過下列規則。只要觸發其中一條,就從統計中排除,並以該規則名稱另行統計。規則在 data/ads-config.json 的 bot_rules 中逐條開關。
| 規則 | 作用 | 目前 |
|---|---|---|
機器人 UA(ua_bot) | 排除搜尋機器人、預覽、腳本(curl、python、headless 等)以及沒有 User-Agent 的請求。 | 開 |
自動化瀏覽器(headless) | 排除開啟 navigator.webdriver 的瀏覽器、HeadlessChrome、PhantomJS、Electron、jsdom,以及沒有 Accept-Language 的請求。這是測量定義,不算作對腳本的防禦。 | 開 |
分頁可見性與焦點(visibility_focus) | 曝光只在分頁可見(document.visibilityState = visible)且視窗有焦點時計入,顯示時間只在分頁可見時計入。這是測量定義。 | 開 |
viewable 判定(min_view) | 模型的規定比例以上在畫面內、達規定面積以上、持續超過規定時間,才算曝光 1 次。這是測量定義。 | 開 |
同一人·同一網路位址重複限制(repeat_limit) | 同一人、同一模型的曝光與點擊在規定時間內計一次,進入(含從門進入)每天一次,並在規定天數內最多規定次數。超過單一網路位址群組每小時上限、每個空間每日新觀眾數、每個活動與空間每日曝光·點擊·進入數的部分予以排除。進入限制會以伺服器的事件紀錄再次核對,伺服器重新啟動也不會遺忘。 | 開 |
伺服器簽署權杖(signed_token) | 事件必須攜帶 serve 提供的簽署權杖(HMAC)。觀看者與 serve 時的網路位址群組會簽署寫入權杖,來自其他位址的曝光予以排除,serve 後未過規定時間的曝光也予以排除。權杖在有效期間內曝光、點擊、進入各只計一次。活動預算在計算時再次核對,超出的事件不計入(budget)。 | 開 |
曝光時間測量(view_time) | 顯示時間只在期間有攝影機或指標輸入時計入,並且只計到每個權杖、每人每模型每日、每個網路位址每模型每日的上限。 | 開 |
空間經營者本人流量(owner_traffic) | 來自開啟過該空間管理畫面的網路位址的事件,在規定天數內予以排除。 | 開 |
人工輸入痕跡(human_input) | 點擊只計算瀏覽器標記為人工輸入(isTrusted)的。曝光不看輸入次數(靜靜觀看的人、使用鍵盤或螢幕閱讀器的使用者)。 | 開 |
異常值監控與保留(anomaly) | 一人一天看到超過規定次數的曝光予以排除。CPA 點擊與進入按每個空間每日自動認列數計入,超出部分保留。若點擊·進入率(與排除該空間後的網路比較)、每次空間點擊的曝光、每個網路位址的新觀眾、資料中心占比、同一位址重複、點擊後的進入率超過標準,則保留該空間當月的分潤,由管理員判定。 | 開 |
資料中心網路(asn) | Cloudflare 附加的 x-mm-asn(AS 號碼)屬於雲端或主機代管網路時,排除該事件,占比大時保留該空間。只有當 Cloudflare Transform Rule 一併附加的祕密標頭(origin-auth)與伺服器 env 值一致時才採信,否則該事件的網路記為「未知」,資料中心占比只以已知網路的事件計算。 | 開 |
進入時的真人驗證(turnstile) | 品牌空間進入(/ads/go)必須在 Metamoa 網域上通過 Cloudflare Turnstile 才計入。即使失敗,使用者仍會被送往品牌空間,只是不計入進入。沒有金鑰時的進入予以保留。 | 開 |
曝光真人驗證 (turnstile_imp) | SDK 在隱藏的 metamoa 視窗中執行 Cloudflare Turnstile,把取得的通行憑證(綁定該網路與空間)附在曝光上。通過的計入,驗證失敗的剔除。沒有憑證時只暫扣該次曝光,月底依該空間無法驗證的比例放行或作廢(管理員可以放行)。廣告始終照常顯示。 | 開 |
- 點擊與進入只在該權杖的曝光已先被計入時才計算(否則為 no_impression)。
- 伺服器記憶的表格滿了時,不刪除尚未到期的紀錄,而是不再計算新事件(capacity)。採取封鎖一方的關閉策略。
事件規格
SDK 請求只接受來自該空間網站的請求。空間經營者自己的網域須為同一註冊網域,github.io、vercel.app 等共用主機須主機名稱完全相同,位於路徑下的空間(github.io/<儲存庫>、claude.ai)則 Referer 路徑也須在其下(SDK 會傳送完整的 Referer)。全部開放 CORS,JSON。也接受 sendBeacon(text/plain)。
取得廣告 · serve
GET https://metamoa.com/ads/v1/serve?space={space_id}&key={mm_adpub_…}&slot={자리 이름 또는 id}&vid={vid}
→ 200 {
"space_id": "onsen-village",
"vid": "<새 브라우저 id: 이 브라우저에 id가 없을 때만 와요>",
"slot": {
"id": "sl_k2m9x0a1b2c3d4e5",
"name": "plaza-front",
"kind": "floor",
"position": [
0,
0,
-8
],
"rotation": [
0,
0,
0
],
"size": [
4,
4,
4
],
"scale": [
0.25,
4
],
"roam": 0
},
"ad": {
"campaign_id": "cp_q8w7e6r5t4y3u2i1",
"brand": "반짝 우유",
"token": "<serve 토큰>",
"enter_url": "https://metamoa.com/ads/go?t=<serve 토큰>",
"kind": "building",
"building_id": "billboard-low",
"model_url": "https://metamoa.com/ads/models/billboard-low/billboard-low.image.glb?v=1",
"size_m": [
4,
2.24,
0.575
],
"mode": "image",
"faces": [
{
"id": "main",
"mesh": "ad_image",
"image_url": "https://metamoa.com/ads/a/as_a1b2c3d4e5f6g7h8.webp"
}
]
}
}
ad 為 null 表示該廣告位目前沒有可投放的廣告。kind 為 model 時放置 model_url 的 glb,為 building 時放置建築 glb 後,mode 為 image 則在 faces 的 mesh 名稱上貼 image_url 的圖片,為 texture 則在全部 texture.meshes 上依 repeat 次數重複貼上 image_url。為 character 時立起角色 glb,在 prop.attach 位置掛上道具,並在其牌面放入 image_url 的圖片或 text 文字。全部配合 slot.size 方框,但只在原始尺寸的 slot.scale 倍率範圍內放大縮小。
登記廣告位 · slots
POST https://metamoa.com/ads/v1/slots
{
"space": "{space_id}",
"key": "{mm_adpub_…}",
"name": "plaza-front",
"kind": "floor",
"position": [
0,
0,
-8
],
"rotation": [
0,
90,
0
],
"size": [
4,
4,
4
],
"scale": [
0.5,
2
],
"industries": [
"game",
"food"
]
}
→ 201 { "slot": {…, "enabled": false} } (새 자리, 공간운영자가 켤 때까지 꺼짐) · 200 (같은 이름의 자리를 바꾸지 않고 그대로)
傳送事件 · events
POST https://metamoa.com/ads/v1/events
{
"space": "onsen-village",
"key": "mm_adpub_XXXXXXXXXXXXXXXXXXXXXX",
"events": [
{
"type": "imp",
"token": "<serve 토큰>",
"ms": 2100,
"area": 0.04,
"inside": 1,
"vis": true,
"focus": true,
"inputs": 3,
"wd": false
},
{
"type": "time",
"token": "<serve 토큰>",
"ms": 5000,
"vis": true,
"inputs": 2,
"wd": false
},
{
"type": "click",
"token": "<serve 토큰>",
"trusted": true,
"wd": false
}
]
}
→ 200 { "accepted": 3, "excluded": 0 }
| type | 欄位 | 意義 |
|---|---|---|
| imp | token, ms, area, inside, vis, focus, inputs, wd | ms:連續顯示時間,area:模型面積占畫面面積的比例(0~1),inside:模型在畫面內的比例(0~1),vis·focus:分頁可見·視窗焦點,inputs:期間攝影機與指標輸入次數,wd:navigator.webdriver |
| time | token, ms, vis, inputs, wd | 上次 time 之後的顯示時間(最多 15,000ms)及期間的輸入次數 |
| click | token, trusted, wd | 點按或點擊了廣告。trusted:人工輸入(isTrusted) |
曝光與 SDK 從隱藏的 metamoa 視窗(Cloudflare Turnstile)取得的真人驗證憑證一起計數。廣告不等待驗證,立即顯示。如果你的網站送出 Content-Security-Policy,請在 frame-src 加入 https://metamoa.com。視窗被封鎖或沒有憑證時,該次曝光會被暫扣;月底後,若該空間無法驗證的比例在 20% 以下則放行,超過則作廢。
每次最多 20 個。事件中不傳送 vid,觀看者使用權杖內的值。錯誤的事件與其他空間的權杖只計為 excluded。
進入 · go
進入只在 Metamoa 網域的 /ads/go 透過 Cloudflare Turnstile 確認是真人之後才計入(有金鑰時會顯示 1~2 秒的小確認畫面)。確認失敗時人仍會前往品牌空間,只是不計入進入。
GET https://metamoa.com/ads/go?t={serve 토큰}
→ 302 Location: {brand_url} (노출이 센 토큰이면 입장을 센 뒤 브랜드 공간으로. 캠페인이 집행 중·기간 안이고 토큰이 유효 시간 안일 때만 검수에서 승인된 brand_url로 가고, 아니면 Location: /)廣告建築、角色與上傳規格
沒有模型的廣告主可以選擇我們提供的廣告建築或基本廣告角色。建築二選一:圖片型(在規定的牌面上各放一張圖片)· 材質型(在整個建築表面貼一張材質或圖樣)。
材質型請下載預設底圖(正方形 PNG),修改後以相同尺寸(1024~2048px)上傳。有線底圖的粉紅色線是表面區塊的邊界,只在區塊內部上色就會顯示在該表面上。
廣告商店(shop-ad)上傳的一張圖片會顯示在正面、側面、背面與頂面:正面招牌、兩側、背面、屋頂上的牌面比例相同,從任何方向看、從上往下看都看得到。附有門,可以使用「從門進入」("door": true)。
基本廣告角色不論金額多少都免費。它們站在或走動於 character 廣告位,把頸掛牌、識別證、手舉牌、氣球、旗子、購物袋等道具綁在骨架上拿著,道具牌面上可放廣告圖片或招牌文字(最多 12 個字)。貓、狗與 Vincent 只能使用掛在脖子上的道具。
| 角色 | id | 可持道具 | 授權 |
|---|---|---|---|
| Changmoa | changmoa | prop-neck-sign prop-badge prop-picket prop-balloon prop-flag prop-shopping-bag | CC0 1.0 |
| Metappyeoseu | metabbyeos | prop-neck-sign prop-badge prop-picket prop-balloon prop-flag prop-shopping-bag | CC0 1.0 |
| Bulk Uploader | bulkuploader | prop-neck-sign prop-badge prop-picket prop-balloon prop-flag prop-shopping-bag | CC0 1.0 |
| Hotspot Wizard | hotspot | prop-neck-sign prop-badge prop-picket prop-balloon prop-flag prop-shopping-bag | CC0 1.0 |
| Bangjang Knight | bangjang | prop-neck-sign prop-badge prop-picket prop-balloon prop-flag prop-shopping-bag | CC0 1.0 |
| Teolgalide | teolgal | prop-neck-sign prop-badge prop-picket prop-balloon prop-flag prop-shopping-bag | CC0 1.0 |
| Nailbus | neilbus | prop-neck-sign prop-badge prop-picket prop-balloon prop-flag prop-shopping-bag | CC0 1.0 |
| Linkblin | linkblin | prop-neck-sign prop-badge prop-picket prop-balloon prop-flag prop-shopping-bag | CC0 1.0 |
| Diablong | diablong | prop-neck-sign prop-badge prop-picket prop-balloon prop-flag prop-shopping-bag | CC0 1.0 |
| Vincent | vincent | prop-neck-sign prop-badge | 自有(FLOAT Co., Ltd.) |
| Nyangjupgo 短毛貓 | cat_short | prop-neck-sign prop-badge | CC BY 4.0 |
| Nyangjupgo 長毛貓 | cat_long | prop-neck-sign prop-badge | CC BY 4.0 |
| Nyangjupgo 曼赤肯貓 | cat_munchkin | prop-neck-sign prop-badge | CC BY 4.0 |
| Nyangjupgo 柯基 | dog_corgi | prop-neck-sign prop-badge | CC BY 4.0 |
| 道具 | id | 圖片比例·最小尺寸 |
|---|---|---|
| 頸掛牌(識別證款) | prop-badge | 720:1024,360×512px 以上 |
| 氣球 | prop-balloon | 1024:1024,512×512px 以上 |
| 手旗 | prop-flag | 1024:688,512×344px 以上 |
| 掛在脖子上的牌子 | prop-neck-sign | 1024:720,512×360px 以上 |
| 手舉牌 | prop-picket | 1024:720,512×360px 以上 |
| 購物袋 | prop-shopping-bag | 1024:1024,512×512px 以上 |
- 圖片格式:PNG · JPEG · WEBP,最大 2MB,寬高最大 4096px,比例誤差最多 2%。上傳的圖片會重新儲存為 WebP(照片資訊會被刪除)。
- 3D 模型:一個 glTF 2.0 二進位(.glb)檔案,最大 6MB,材質包含在檔案內,不含外部位址(uri)。
- 上傳的檔案依內容(魔術位元組)確認格式:圖片只接受 PNG、JPEG、WebP(不接受 SVG、HTML 等)並重新產生為 WebP,模型只接受 glTF 2.0 二進位。廣告檔案只以固定類型(image/webp、model/gltf-binary)、nosniff、sandbox 政策提供,不會作為腳本執行。
- 廣告模型的大小可能會依空間由空間經營者或 Metamoa 調整。
- 模型與角色檔案位於 /ads/models/ 下,只以不允許腳本的回應(固定類型、nosniff、sandbox)提供。清單與出處見 docs/ads/MODELS.md,修改時用 scripts/ads-import-models.mjs 一併重新產生 data/ads-buildings.json 與檔案。
模型出處標示
基本模型大多為 CC0(公眾領域)或自製,以下為 CC BY,因此標明出處。全部由 FLOAT Co., Ltd. 修改了尺寸、廣告面等。
- 立式廣告看板:"Blank Billboard" by Jarlan Perez(https://poly.pizza/m/1E0d2B7bC8e),CC BY 3.0(https://creativecommons.org/licenses/by/3.0/),FLOAT Co., Ltd. 修改
- 快閃攤位:"Carnival Booth" by sirkitree(https://poly.pizza/m/4NizXJZsuO2),CC BY 3.0(https://creativecommons.org/licenses/by/3.0/),FLOAT Co., Ltd. 修改
- 公車站廣告看板:"Bus Stop" by Zsky(https://poly.pizza/m/OWczicNWhO),CC BY 3.0(https://creativecommons.org/licenses/by/3.0/),FLOAT Co., Ltd. 修改
- A 字立牌:"Sandwich Board" by Anonymous(https://poly.pizza/m/ejy0W_7cHWT),CC BY 3.0(https://creativecommons.org/licenses/by/3.0/),FLOAT Co., Ltd. 修改
- Nyangjupgo 短毛貓:"Cat" by Polyfork(https://polyfork.dev/asset/cat-base),CC BY 4.0,FLOAT Co., Ltd. 改為體素
- Nyangjupgo 長毛貓:"Cat" by Polyfork(https://polyfork.dev/asset/cat-base),CC BY 4.0,FLOAT Co., Ltd. 改為體素
- Nyangjupgo 曼赤肯貓:"Cat" by Polyfork(https://polyfork.dev/asset/cat-base),CC BY 4.0,FLOAT Co., Ltd. 改為體素
- Nyangjupgo 柯基:"Dog" by Polyfork(https://polyfork.dev/asset/dog-base),CC BY 4.0,FLOAT Co., Ltd. 改為體素
模型製作請求
廣告主選擇「模型製作請求」後,我們會製作 3D 模型並附加到活動中,然後進行審核。製作資料(產品照片、標誌、圖面)請連同活動編號寄至 [email protected]。
| 等級 | grade | 製作費 | 投放媒體費達此金額以上即免費 |
|---|---|---|---|
| 簡單產品·招牌 | simple | ₩50,000(供貨價,未稅) | ₩500,000 |
| 精細產品 | precise | ₩100,000(供貨價,未稅) | ₩1,000,000 |
| 新角色 | character | ₩100,000(供貨價,未稅) | ₩1,000,000 |
- 免費標準以實際投放媒體費計算(整個合約期間合計,最長 3 個月,不含建模費、營業稅與無效流量)。
- 免費製作的模型只提供在 Metamoa 播放的使用權(著作權歸 Metamoa,轉讓需支付製作費),可修改 1 次。因廣告主因素解約或減額時,依比例收取製作費:製作費 × (1 − 實際投放媒體費 ÷ 免費標準)。付費模型可修改 2 次。
- 基本廣告角色(Moa 營地·Nyangjupgo 角色)無需製作請求,不論金額多少都可免費使用。
廣告主:自助登記步驟
- 在 https://metamoa.com/ads/manage 用 Metamoa 帳號登入(註冊也在同一視窗)。
- 建立活動:名稱、品牌、產業,品牌空間網址(使用進入 CPA 時)。
- 廣告物:① 上傳自己的 3D 模型(glb)② 選擇廣告建築 → 圖片型為每個牌面放圖片,材質型放一張材質 ③ 選擇基本廣告角色 + 道具 → 在道具牌面放圖片或招牌文字 ④ 模型製作請求(選擇等級)。會顯示規格與預覽。
- 曝光空間:從同意刊登廣告的空間清單中,查看分類、目前線上人數、每日空間點擊後自行選擇廣告位,或點按「推薦」,依產業、分類、流量推薦一組空間。
- 決定計費方式(CPM、CPA、曝光時間、空間固定合約)、預算與期間後申請 → 等待審核。
- 通過審核(猥褻、暴力、涉嫌侵權等)後即開始投放。進行中的活動可以暫停與重新開啟,每天可查看 viewable 曝光、點擊、進入與顯示時間。
PUT https://metamoa.com/api/ads/assets?kind=image&building=billboard-low&face=main (본문: 이미지 파일)
PUT https://metamoa.com/api/ads/assets?kind=image&prop=prop-neck-sign (본문: 이미지 파일)
POST https://metamoa.com/api/ads/recommend {"industry": "food", "count": 5}
POST https://metamoa.com/api/ads/campaigns
{
"name": "겨울 우유 3D",
"brand": "반짝 우유",
"industry": "food",
"billing": "cpm",
"budget_won": 500000,
"start_day": "2026-12-01",
"end_day": "2026-12-31",
"targeting": "recommend",
"slot_ids": [
"sl_k2m9x0a1b2c3d4e5"
],
"brand_url": "https://milk.example/space",
"creative": {
"kind": "building",
"building_id": "billboard-low",
"mode": "image",
"images": {
"main": "as_a1b2c3d4e5f6g7h8"
}
}
}
(헤더: X-Account-Token: mm1.… · X-Device-Id: <기기 id>)
角色廣告物:{"kind": "character", "character_id": "bangjang", "prop": "prop-picket", "image": "as_…"} 或以 "text": "閃亮牛奶" 取代 "image"。空間固定合約:"billing": "fixed", "fixed_period": "week" | "month", end_day = start_day + 期間 − 1。模型製作請求:{"kind": "request", "grade": "simple", "note": "…"}。
建築與自有模型廣告物還可以再加兩項(選填):"tagline": "一句話介紹"(最多 30 個字,僅限文字 — 不可使用標籤、角括號、大括號(400 invalid,fields creative),與廣告物一起審核)會畫在廣告商店或建築招牌下方的條帶(網格 ad_tagline)上,並以 serve 的 ad.tagline { text, mesh, aspect } 回傳。"door": true 即「從門進入」(需要 brand_url)。與 /ads/manage 第 2 步的「一句話介紹」「從門進入」欄相同。
審核
- 上傳的模型、圖片與活動在刊登前處於待審核(review)狀態。管理員核准後投放(active),駁回則保留 rejected 與原因。
- 圖片在上傳時先由 AI 圖片檢測檢查猥褻、暴力、他人標誌或角色,命中則立即封鎖(rejected)。無法檢測時由管理員親自查看。
- 模型由管理員親自開啟查看。如涉及猥褻、暴力或涉嫌侵權則駁回。
錯誤代碼
錯誤內文為 { "error": "<代碼>", "message": "<下一步該做什麼的一句話>" },欄位錯誤會附帶 fields,限額會附帶 retry_after。
| HTTP | error | 意義 |
|---|---|---|
| 400 | invalid | 欄位格式錯誤。fields 中回傳錯誤的欄位。 |
| 400 | bad_model | 不是 glb、不是 glTF 2.0,或包含外部位址(uri)。原因見 reason。 |
| 400 | bad_image | 圖片格式、大小或比例與規格不符。會回傳 reason(format · bytes · too_large · too_small · aspect)與 spec。 |
| 400 | bad_building | 廣告位的 default_building 不是 GET /ads/v1/buildings 中的建築或立牌 id(空值可以)。 |
| 400 | slot_unavailable | 所選廣告位不接收廣告、不接收該產業,或與廣告物類型不符(角色只能用於角色廣告位)。slot_ids 中回傳這些廣告位。 |
| 401 | unauthorized | 沒有空間金鑰或空間管理登入,或不正確。 |
| 401 | sign_in | 廣告主:沒有 Metamoa 帳號登入,或已過期。 |
| 403 | owner_required | 有空間金鑰,但尚未確認空間經營者身分。 |
| 403 | owner_page_only | 用空間金鑰嘗試條款確認或同意刊登廣告(只能在空間管理畫面操作)。 |
| 403 | bad_ad_key | SDK:space 與 key(mm_adpub_)不符。 |
| 403 | terms_required | 該空間尚未確認廣告刊登條款。 |
| 403 | ads_off | 該空間關閉了同意刊登廣告。 |
| 403 | origin_mismatch | SDK 請求不是來自該空間網站(同一網域)。 |
| 404 | not_house | 在非 Metamoa 直接經營的空間呼叫了我們的廣告(GET /ads/v1/house)。 |
| 403 | not_yours | 廣告主:使用了他人的檔案 id。 |
| 404 | no_slot | 沒有該名稱或 id 的廣告位。 |
| 404 | not_found | 該活動或檔案不存在。 |
| 409 | not_listed | 未列入目錄的空間(核准前或已隱藏)。 |
| 409 | payout_info_required | 想開啟同意刊登廣告,但沒有結算資訊的類型(個人·企業)與聯絡方式(手機或電子郵件)。請在空間管理收益化(/owner/revenue?id=<空間 id>)中填寫。 |
| 409 | advertiser_required | 廣告主:在填寫廣告主資訊(PUT /api/ads/advertiser)之前就想申請或付款活動。 |
| 409 | biz_doc_required | 廣告主:企業廣告主在上傳營業登記證影本(PUT /api/ads/advertiser/doc)之前就付款或申請空間固定合約。 |
| 409 | business_only | 廣告主:個人廣告主想上傳營業登記證影本。 |
| 400 | bad_doc | 廣告主:營業登記證影本不是 PDF、JPG、PNG。 |
| 413 | doc_too_big | 廣告主:營業登記證影本超過 5MB。 |
| 503 | advertiser_unavailable | 廣告主:伺服器沒有廣告主資訊加密金鑰,無法接收。 |
| 409 | email_not_linked | 廣告主:個人廣告主的電子郵件不是登入此 Metamoa 帳號的電子郵件。 |
| 409 | name_taken | 已存在同名的廣告位。 |
| 409 | slot_limit | 每個空間最多 30 個空間經營者廣告位,最多 5 個未確認的 SDK 廣告位。 |
| 409 | slot_taken | 該期間已簽有其他空間固定合約的廣告位。 |
| 409 | tier_too_low | 以空間固定合約選擇了每日空間點擊未達最低等級的空間的廣告位。slot_ids 中回傳這些廣告位。 |
| 409 | not_for_sale | 沒有空間固定合約單價。 |
| 409 | under_minimum | 低於最低投放媒體費。會回傳 min_spend_won、spend_won。 |
| 409 | no_click_history | 為尚無空間點擊紀錄的空間的廣告位選擇了 CPM 或空間固定合約(無法測量曝光量與等級)。只能選 CPA 與曝光時間型。會回傳 slot_ids、billings。 |
| 409 | over_inventory | CPM 預算超過所選廣告位預估 viewable 曝光上限。會回傳 max_budget_won。 |
| 409 | rejected_file | 在活動中使用了審核中被封鎖的檔案。 |
| 409 | wrong_state | 該狀態下無法進行的操作(暫停審核中的活動等)。 |
| 409 | stale | 管理員:開啟審核畫面後活動有了變更(decide 的 version 與目前不同)。請重新查看後再決定。 |
| 409 | already_paid | 想對已付款的活動再次開啟付款。 |
| 409 | not_paid | 管理員:想核准尚未完成付款的活動的結算。 |
| 409 | held | 管理員:想核准有保留分潤的活動的結算(請先判定保留)。 |
| 424 | hrum_failed | 無法連線到付款(Hrum)。請稍後再試。 |
| 503 | pay_not_ready | 暫時無法開啟付款(伺服器設定前)。 |
| 409 | model_missing | 管理員:在為模型製作請求活動附加模型之前就核准了。 |
| 413 | model_too_big | 模型檔案超過 6MB。 |
| 429 | too_many | 請求過多。請等待 Retry-After 指定的秒數。 |
全部路徑
SDK (CORS *, 그 공간 사이트에서)
GET /ads/sdk.js · GET /ads/v1/serve · POST /ads/v1/slots · POST /ads/v1/events · GET /ads/go (Turnstile 화면, 문이면 &via=door) · POST /ads/go · GET /ads/v1/buildings · GET /ads/a/{asset}.glb|webp
공간운영자 (공간 관리 로그인 mm_own_ 또는 공간 키 mm_live_)
GET /api/space/{id}/ads · POST /api/space/{id}/ads/terms · POST /api/space/{id}/ads/consent {"on": true} (이 둘은 공간 관리 로그인만)
GET|POST /api/space/{id}/ads/slots · PATCH|DELETE /api/space/{id}/ads/slots/{slot_id} · GET /api/space/{id}/ads/stats?from=&to=
공간운영자 등급 (공개)
GET /api/ads/partners → 등급표, 남은 자리(플래티넘·골드) · 안내 페이지 /ads/partners
광고 고르기 (공개)
GET /api/ads/options → 업종·과금 방식·건물·업로드 규격·정해진 단가 (로그인 없이 조회 가능)
광고주 (메타모아 계정: X-Account-Token + X-Device-Id)
GET|PUT /api/ads/advertiser (광고주 정보: 사업자 또는 개인, 캠페인 신청·결제 전에 한 번) · PUT /api/ads/advertiser/doc (사업자등록증 사본, 첫 결제·공간 고정 계약 전) · POST /api/ads/production (제작 의뢰: 이름·회사, 연락처, 원하는 것, 예산 범위(선택), 일정 · 로그인 없이) · GET /api/ads/spaces · POST /api/ads/recommend · PUT /api/ads/assets · GET /api/ads/assets · GET /api/ads/assets/{id}/raw
GET|POST /api/ads/campaigns · GET /api/ads/campaigns/{id} · PATCH /api/ads/campaigns/{id} {brand_url} (바꾸면 다시 검수 대기, 승인 전까지 입장은 전에 승인된 주소로) · POST /api/ads/campaigns/{id}/pause|resume · POST /api/ads/campaigns/{id}/pay (흐름 결제 열기)
문서: /ads/docs (사람) · /ads/llms.txt (AI) · /api#ads · /api/openapi.json