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