Quảng cáo 3D của Metamoa · 3D ads
Đăng ký ưu tiên cho nhà vận hành không gian · xem hạng chia doanh thu
Tổng quan
Quảng cáo 3D của Metamoa đặt mô hình 3D, tòa nhà quảng cáo hoặc nhân vật quảng cáo của nhà quảng cáo vào các vị trí quảng cáo trong không gian metaverse trên web, chỉ đếm những gì người thật đã xem và đã làm, thu phí quảng cáo theo đó và chia phần cho các nhà vận hành không gian. Với tư cách doanh nghiệp quảng cáo và đại lý quảng cáo, chúng tôi nhận từ doanh nghiệp lớn đến doanh nghiệp vừa và nhỏ.
- Nhà vận hành không gian: trong mục Kiếm tiền của trang quản lý không gian (/owner/revenue), dùng 「Đăng ký nhận quảng cáo」 (xác nhận điều khoản, thông tin thanh toán, vị trí quảng cáo) → thêm một dòng script và các vị trí quảng cáo là xong.
- Nhà quảng cáo: đăng nhập bằng tài khoản Metamoa tại /ads/manage → tải lên mô hình 3D (glb), hoặc chọn tòa nhà quảng cáo rồi thêm ảnh hay texture, hoặc chọn đạo cụ và quảng cáo cho nhân vật quảng cáo cơ bản → tự chọn không gian hiển thị hoặc dùng 「Gợi ý」 → cách tính phí, ngân sách và thời gian → chạy sau khi duyệt.
- Chưa có mô hình? Chọn 「Yêu cầu làm mô hình」, chúng tôi sẽ làm cho bạn. Chúng tôi cũng nhận mô hình bạn tự gửi. Nhân vật quảng cáo cơ bản miễn phí với mọi mức chi.
- Có bốn cách tính phí: CPM (lượt hiển thị viewable), CPA (lượt nhấp vào mô hình, lượt vào không gian thương hiệu), thời gian hiển thị (tổng thời gian được nhìn thấy) và hợp đồng vị trí cố định (theo kỳ, độc quyền vị trí). Mọi số tiền đều là (giá chưa thuế, chưa gồm VAT).
- Kích thước mô hình quảng cáo có thể được nhà vận hành không gian hoặc Metamoa điều chỉnh tùy theo không gian.




4 sản phẩm và cách tính phí
Mọi số tiền đều là giá chưa thuế, chưa gồm VAT.
| Sản phẩm | billing | Thứ được đếm | Đơn giá |
|---|---|---|---|
| CPM (lượt hiển thị viewable) | cpm | 1 lượt hiển thị viewable = mô hình nằm trên màn hình ít nhất một tỷ lệ nhất định, liên tục lâu hơn một khoảng thời gian nhất định (khi tab đang hiển thị) | ₩8,000 mỗi 1,000 lượt viewable |
| CPA · nhấp vào mô hình | cpa | Chạm hoặc nhấp vào mô hình quảng cáo. Nếu sau khi nhấp mà vào tiếp không gian thương hiệu thì chỉ tính 1 lượt vào | ₩700 mỗi 1 lượt nhấp |
| CPA · vào không gian thương hiệu | cpa | Chạm vào quảng cáo và vào không gian thương hiệu (brand_url). Đếm bằng chuyển hướng máy chủ (/ads/go); mỗi người, mỗi chiến dịch một lần mỗi ngày | ₩1,000 mỗi 1 lượt vào |
| Thời gian hiển thị | time | Tổng thời gian quảng cáo được nhìn thấy sau lượt hiển thị viewable (chỉ khi có thao tác, tối đa đến mức trần mỗi ngày cho mỗi người và mô hình) | ₩1,000 mỗi 1,000 giây viewable |
| Hợp đồng vị trí cố định | fixed | Theo kỳ (tối đa một tháng). Bạn độc quyền dùng vị trí quảng cáo đã ký trong kỳ đó (theo từng vị trí). Không đảm bảo số lượt hiển thị | Xem bảng hạng bên dưới |
Hạng của hợp đồng vị trí cố định
Hạng được xác định theo trung vị số lượt nhấp không gian sạch mỗi ngày trong 14 ngày gần nhất của không gian chứa vị trí đó (không tính lượt vào của chính nhà vận hành, mạng trung tâm dữ liệu và trình duyệt tự động; “Vào” của metamoa chỉ tính sau khi qua xác minh người thật). Vị trí ở không gian chưa đạt hạng thấp nhất không bán theo hợp đồng vị trí cố định, chỉ nhận theo hiệu quả. Thời hạn hợp đồng là theo tuần (7 ngày) hoặc theo tháng (30 ngày).
| Hạng | Lượt nhấp không gian mỗi ngày | Theo tuần (1 vị trí) | Theo tháng (1 vị trí) |
|---|---|---|---|
| S | Từ 1,000 trở lên | ₩50,000 | ₩180,000 |
| A | 300~999 | ₩15,000 | ₩50,000 |
| B | 100~299 | ₩5,000 | ₩18,000 |
- Mức chi tối thiểu: phí truyền thông ₩10,000 (giá chưa thuế, chưa gồm VAT), không tính phí làm mô hình. Loại theo hiệu quả tính theo ngân sách, hợp đồng vị trí cố định tính theo tổng giá trị hợp đồng.
- Loại theo hiệu quả (CPM, CPA, thời gian hiển thị) chỉ tính phí đúng phần đã thực sự đếm, và chiến dịch sẽ ngừng chạy khi số tiền đã chi chạm ngân sách (budget_won).
- Hợp đồng CPM chỉ được nhận đến 70% số lượt hiển thị viewable dự kiến của các vị trí đã chọn (lượt nhấp không gian mỗi ngày × 0.7 × số ngày) (409 over_inventory).
- Loại CPA và thời gian hiển thị không bị chặn, nhưng nếu ngân sách lớn hơn mức chi dự kiến, /ads/manage sẽ báo trước khi đăng ký: trên cùng số lượt hiển thị viewable dự kiến, CPA nhân với tỷ lệ nhấp chuẩn 2% × giá lớn hơn giữa giá nhấp và giá vào, thời gian hiển thị nhân với 60 giây mỗi người mỗi ngày (spend_estimate của GET /api/ads/options).
- Vị trí đã có hợp đồng vị trí cố định chỉ chạy đúng chiến dịch đó trong kỳ, và không nhận hợp đồng cố định khác cho cùng vị trí với thời gian chồng lấn (409 slot_taken). Vị trí được giữ khi được duyệt: đơn đang chờ duyệt không giữ vị trí, hợp đồng được duyệt trước sẽ thắng. Nếu có ngày mô hình không hiện hoặc lưu lượng giảm hơn 30%, chúng tôi bù bằng hoàn tiền theo ngày hoặc gia hạn.
- Việc tính phí và xếp hạng dựa trên báo cáo đo thực tế của Metamoa (lượt hiển thị viewable, lượt nhấp, lượt vào, thời gian hiển thị, lượt nhấp không gian).
Công thức tổng hợp
Ngày tính theo giờ Hàn Quốc, mỗi ngày một đơn vị (ad_daily). Số tiền là giá chưa thuế đã bỏ phần lẻ dưới một won. Sự kiện vi phạm quy tắc không được đếm và được đếm riêng theo lý do (ad_excluded).
- Lượt hiển thị viewable imps = số sự kiện
impđã qua mọi quy tắc - Lượt nhấp clicks = số
clickđã qua, lượt vào enters = số lượt vào (/ads/go) đã qua, converted = số lượt nhấp rồi vào bằng cùng một token - Thời gian hiển thị view_ms = tổng ms của các sự kiện
timeđã qua (chỉ token đã được đếm lượt hiển thị, tối đa 15,000ms mỗi sự kiện, tối đa đến mức trần mỗi ngày cho mỗi người và mô hình) - Số tiền CPM = floor(imps × cpm_won ÷ 1,000)
- Số tiền CPA = (clicks − converted) × click_won + enters × enter_won
- Số tiền thời gian hiển thị = floor(view_ms ÷ 1,000 × time_1000s_won ÷ 1,000)
- Số tiền hợp đồng vị trí cố định = tổng đơn giá theo hạng của từng vị trí đã ký. Khi chỉ tổng hợp một phần của kỳ, mỗi vị trí là floor(đơn giá × số ngày hợp đồng trong kỳ đó ÷ số ngày hợp đồng)
- Phần của nhà vận hành không gian = floor(số tiền theo không gian × tỷ lệ hạng của nhà vận hành không gian đó (%) ÷ 100). Số tiền là giá truyền thông chưa thuế sau khi trừ lưu lượng không hợp lệ; phí làm mô hình và không gian không được chia. Hạng: xem 「Hạng chia doanh thu cho nhà vận hành không gian」 bên dưới.
Hạng chia doanh thu cho nhà vận hành không gian
Doanh thu quảng cáo (số tiền truyền thông quảng cáo theo không gian, giá chưa thuế sau khi trừ lưu lượng không hợp lệ) được chia giữa nhà vận hành không gian và Metamoa theo tỷ lệ của hạng. Áp dụng từ ngày 11/11/2026. Đăng ký ưu tiên: https://metamoa.com/ads/partners
| Hạng | Đối tượng | Nhà vận hành không gian : Metamoa |
|---|---|---|
| Bạch kim | Theo thứ tự đến trước: nhà vận hành không gian thứ 1~10 | 9:1 |
| Vàng | Nhà vận hành không gian thứ 11~100 (90 người) | 8:2 |
| Bạc | Các nhà vận hành không gian sau đó | 7:3 |
| Đồng | Nhà vận hành không gian ký hợp đồng mới từ ngày 1/1/2027 | 6:4 |
Tỷ lệ có thể được điều chỉnh sau này tùy theo hiệu quả quảng cáo.
- Nhà vận hành không gian = một tài khoản sở hữu đã đăng ký không gian trên Metamoa và đăng nhập vào trang quản lý không gian. Thứ tự là thời điểm mỗi người lần đầu bật 「Đồng ý hiển thị quảng cáo」 trong trang quản lý không gian, do máy chủ đánh số lần lượt từng người.
- Hạng một khi đã định sẽ được giữ nguyên, và các không gian khác của cùng nhà vận hành cũng cùng hạng.
- Nhà vận hành không gian ký hợp đồng mới từ 0 giờ ngày 1/1/2027 (giờ Hàn Quốc) đều là hạng Đồng, bất kể thứ tự.
- Hạng và tỷ lệ của tôi: ô 「Quảng cáo 3D」 trong trang quản lý không gian, partner của GET /api/space/{id}/ads. Suất còn lại: seats của GET /api/ads/partners.
- Suất còn lại hiện tại: Bạch kim 0/10 · Vàng 80/90
Xác nhận điều khoản và đồng ý hiển thị quảng cáo
Điều khoản sử dụng đã có điều khoản về hiển thị quảng cáo (Điều 4-4). Để nhận quảng cáo, nhà vận hành không gian làm hai việc cùng lúc trong 「Đăng ký nhận quảng cáo」 ở mục Kiếm tiền của trang quản lý không gian.
- Xác nhận điều khoản: đánh dấu xác nhận điều khoản ở bước 1 của 「Đăng ký nhận quảng cáo」 trong trang quản lý không gian (/owner/revenue?id=<id không gian>). Chỉ làm được trong trang quản lý không gian (bằng khóa không gian sẽ ra 403 owner_page_only).
- Đồng ý hiển thị quảng cáo: bật cùng lúc với xác nhận điều khoản, sau đó bật tắt theo từng không gian trên cùng màn hình. Để bật cần có loại thông tin thanh toán và thông tin liên hệ (nếu không có là 409 payout_info_required). Phải bật thì API quảng cáo của không gian đó (một dòng script, khóa quảng cáo) mới hiện, tắt thì quảng cáo ngừng ngay (serve 403 ads_off).
Hồ sơ đồng ý: không gian, ai (mã băm email đăng nhập của nhà vận hành vào trang quản lý không gian đó), khi nào, phiên bản điều khoản nào (data-ads-version của terms.html), bật hay tắt đều được lưu tích lũy, không xóa (ad_consents).
Không gian chưa xác nhận điều khoản hoặc đã tắt đồng ý hiển thị quảng cáo, và không gian chưa được đưa vào danh sách sẽ không có quảng cáo.
Vị trí quảng cáo (slot)
Nhà vận hành không gian tự quyết định chỗ đặt quảng cáo trong metaverse của mình. Nhà quảng cáo chọn theo vị trí hoặc nhận gợi ý, hợp đồng vị trí cố định cũng ký theo vị trí. Danh sách vị trí có thể xem và bật tắt trong trang quản lý không gian.
| Trường | Định dạng | Ý nghĩa |
|---|---|---|
| name | 1~40 ký tự | Tên không trùng trong không gian |
| kind | floor · wall · air · character | Mô hình đặt sàn · biển hiệu tường · băng rôn trên không · nhân vật quảng cáo đứng hoặc đi lại |
| position | [x, y, z] mét | Vị trí tâm đáy của hộp vị trí (tọa độ không gian) |
| rotation | [x, y, z] độ (-360~360) | Góc xoay của vị trí. Mặc định [0, 0, 0] |
| size | [rộng, cao, sâu] mét (0.1~200) | Hộp chứa quảng cáo. Quảng cáo được phóng to hoặc thu nhỏ cho vừa hộp này |
| scale | [tối thiểu, tối đa] lần (0.05~20) | Hệ số kích thước theo không gian: khi khớp vào hộp, quảng cáo chỉ được phóng to thu nhỏ trong phạm vi hệ số này so với kích thước gốc. Mặc định [0.25, 4] |
| roam | 0~50 mét | Vị trí character: bán kính nhân vật đi lại (0 là đứng yên) |
| industries | Danh sách id ngành | Các ngành vị trí này nhận. Để trống là mọi ngành |
| enabled | true · false | Khi tắt, vị trí này không hiện quảng cáo |
Kích thước mô hình quảng cáo có thể được nhà vận hành không gian hoặc Metamoa điều chỉnh tùy theo không gian.
Quảng cáo nhân vật chỉ chạy ở vị trí character, quảng cáo mô hình và tòa nhà chỉ chạy ở vị trí floor, wall, air.
SDK (khóa quảng cáo công khai) chỉ tạo được vị trí mới, và vị trí tạo như vậy ở trạng thái tắt; nhà vận hành phải kiểm tra và bật trong trang quản lý không gian thì quảng cáo mới chạy. Vị trí đã có (cùng tên) thì SDK không sửa được và trả về nguyên trạng. Vị trí SDK đang tắt tối đa 5 cái mỗi không gian, đếm riêng với 30 vị trí của nhà vận hành. Một nhóm IP mỗi ngày tạo được tối đa 20 cái, và vị trí SDK mà nhà vận hành không bật lần nào trong 7 ngày sẽ bị xóa (vị trí từng bật và vị trí chiến dịch đang dùng thì không xóa). Khi bật, chúng được tính trong 30 vị trí của nhà vận hành. Đổi hộp, loại, ngành của vị trí và bật tắt chỉ làm được bằng đăng nhập trang quản lý hoặc khóa không gian.
Id ngành: game (trò chơi) · fashion (thời trang, làm đẹp) · food (ăn uống) · tech (CNTT, điện tử) · finance (tài chính) · edu (giáo dục) · travel (du lịch, giải trí) · culture (văn hóa, giải trí) · auto (ô tô) · public (công, phi lợi nhuận) · etc (khác)
Mỗi không gian tối đa 30 vị trí. API vị trí dùng khóa không gian (mm_live_) hoặc đăng nhập trang quản lý không gian:
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}Nhà vận hành không gian: các bước gắn
- Trong 「Đăng ký nhận quảng cáo」 ở mục Kiếm tiền của trang quản lý không gian (
https://metamoa.com/owner/revenue?id=<id không gian>), đánh dấu xác nhận điều khoản và bắt đầu quảng cáo. - Đặt dòng script ở ô 「API quảng cáo」 của cùng màn hình vào cuối <head> hoặc <body> của trang không gian. Khóa quảng cáo (mm_adpub_) có thể công khai (đừng đặt khóa không gian mm_live_ vào đó).
- Với không gian three.js, gọi attach và slot sau khi cảnh đã được dựng. Vị trí được đăng ký ở trạng thái tắt ở lần gọi đầu tiên. Bật trong 「Vị trí quảng cáo」 của trang quản lý thì quảng cáo sẽ chạy (cũng có thể tạo ở trạng thái bật ngay từ đầu bằng API vị trí).
- Quảng cáo hiện ra là xong. Lượt hiển thị viewable, lượt nhấp và thời gian hiển thị do SDK tự gửi, còn lượt vào không gian thương hiệu thì khi chạm quảng cáo SDK mở /ads/go và máy chủ đếm.
- Trong 「Vị trí quảng cáo」 của trang quản lý không gian, bật tắt vị trí và xem số liệu 30 ngày (trước và sau khi áp quy tắc) cùng phần được chia (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 });
});
Engine không phải three.js (Babylon.js, PlayCanvas, Unity WebGL…) nhận quảng cáo bằng serve, tự vẽ và gửi sự kiện: ads.serve(name) → { ad }, ads.report(name, event). Với lượt vào, chỉ cần mở ad.enter_url trong cửa sổ mới hoặc cùng cửa sổ. Quy cách xem ở 「Quy cách sự kiện」 bên dưới.
Cách SDK đếm
- Lượt hiển thị viewable: khi ít nhất một tỷ lệ nhất định của mô hình nằm trong khung camera, kích thước trên màn hình từ một diện tích nhất định trở lên, kéo dài quá một khoảng thời gian nhất định trong lúc tab đang hiển thị, SDK gửi 1 lượt hiển thị (mỗi token serve một lần).
- Thời gian hiển thị: sau lượt hiển thị, trong lúc quảng cáo còn được nhìn thấy theo điều kiện trên, cứ 5 giây cộng dồn và gửi một lần, kèm số lần thao tác camera và con trỏ trong khoảng đó (dừng khi tab bị ẩn).
- Nếu phản hồi serve có vid thì lưu trong trình duyệt đó và gửi kèm từ lần serve tiếp theo (GET /ads/v1/serve?…&vid=). Chỉ vid do máy chủ ký cho mạng đó mới được đọc. Máy chủ gộp vid với nhóm IP kết nối và ký người đó vào token. Lượt hiển thị chỉ được đếm sau serve khoảng 2 giây.
- Nhấp: chạm hoặc nhấp vào quảng cáo thì gửi
click, và nếu quảng cáo có không gian thương hiệu thì mở enter_url (/ads/go) trong cửa sổ mới. Máy chủ đếm lượt vào và chuyển sang không gian thương hiệu. - Cửa: nếu có ad.door, khi đi bộ vào qua cửa sẽ mở enter_url một lần trong cửa sổ mới. Điều kiện mở lại xem ở 「Đi vào qua cửa」 bên dưới.
- Id trình duyệt (vid) do máy chủ cấp và SDK lưu trong localStorage. Chỉ dùng cho giới hạn lặp lại. Không gửi thông tin cá nhân như tên hay liên hệ.
- Quảng cáo được nhận mới mỗi 30 phút (token mới). Nhân vật ở vị trí character đi chậm trong bán kính roam.
Đi vào qua cửa
Bạn có thể gắn cửa cho tòa nhà quảng cáo hoặc mô hình 3D của mình. Đây là cửa, không phải cổng dịch chuyển: khi người dùng đi bộ vào qua cửa, không gian hiện tại vẫn giữ nguyên và không gian thương hiệu mở trong cửa sổ mới (tab mới). Thêm "door": true vào creative của chiến dịch (chỉ khi kind là model hoặc building), và cần có brand_url (nếu không có là 400 invalid, fields brand_url). ad của serve sẽ có 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 } }
Quy tắc để cửa không mở lại liên tục (bắt buộc tuân thủ)
- Khi đi bộ vào trong vòng 1.2m trước cửa, không gian thương hiệu (enter_url có &via=door) mở một lần trong cửa sổ mới.
- Sau khi đóng cửa sổ mới mở và quay lại, dù di chuyển một chút trong hoặc gần cửa, cửa cũng không mở lại.
- Phải đi ra xa cửa hơn 3m rồi quay vào thì cửa mới mở lại (khoảng cách vào 1.2m < khoảng cách ra 3m).
- Trong lúc tab bị ẩn hoặc cửa sổ không có tiêu điểm thì không mở, và sau khi quay lại cũng phải ra khỏi khu vực cửa một lần. Nếu lúc mở trang đã đứng sẵn trong cửa thì cũng không mở.
- Chạm hoặc nhấp vào tòa nhà để mở vẫn như cũ (mỗi lần nhấp). Quy tắc cửa chỉ áp dụng cho việc đi bộ vào.
- Nếu trình duyệt chặn cửa sổ mới, nút 「Mở <thương hiệu>」 sẽ hiện ở cuối màn hình. Phải bấm nút đó mới mở (nếu rời cửa mà không bấm thì nút biến mất).
Vị trí cửa: nếu trong glb có nút tên door thì dùng nút đó, không có thì SDK vẽ cửa mặc định ở giữa phía dưới mặt trước quảng cáo (+Z). Khoảng cách là khoảng cách trên sàn từ nhân vật đang đi đến trước cửa. Hãy truyền cho attach một walker (Object3D của nhân vật đang đi hoặc hàm trả về {x, y, z}). Nếu không có thì đo theo vị trí camera.
ads.attach({ THREE, GLTFLoader, scene, camera, renderer, walker: player }); // player: the walking character (Object3D)
Không gian tự vẽ ad.door bằng engine không phải three.js cũng phải tuân thủ y hệt quy tắc trên: sau khi mở một lần, không mở lại cho đến khi ra ngoài exit_m; và sau khi tab bị ẩn rồi quay lại, không mở lại cho đến khi ra khỏi khu vực cửa một lần.
Để ra vào liên tục không làm hao ngân sách
- Lượt vào qua cửa được tính cùng đơn giá với 1 lượt vào CPA (đơn giá và mức chi tối thiểu giữ nguyên).
- Lượt vào của một người (id trình duyệt do máy chủ cấp + nhóm địa chỉ internet) cho một chiến dịch chỉ được đếm một lần mỗi 24 giờ, tối đa 3 lần trong 30 ngày. Cùng nhóm địa chỉ internet tối đa 3 lần mỗi ngày cho mỗi chiến dịch và không gian.
- Các lượt ra vào vượt mức đó vẫn được chuyển sang không gian thương hiệu nhưng không tính phí, chỉ ghi lại (lý do loại trừ repeat_limit). Được kiểm tra lại bằng nhật ký sự kiện của máy chủ (chỉ mã băm) nên máy chủ khởi động lại cũng không quên.
- Lượt vào với cùng token serve chỉ đếm một lần, và chỉ đếm token đã được đếm lượt hiển thị trước (giữ nguyên quy tắc kiểm tra bot và gian lận).
Quy tắc kiểm tra bot và gian lận
Sự kiện lần lượt đi qua các quy tắc dưới đây trên máy chủ. Chỉ cần vướng một quy tắc là bị loại khỏi số liệu và đếm riêng theo tên quy tắc đó. Mỗi quy tắc được bật tắt riêng trong bot_rules của data/ads-config.json.
| Quy tắc | Việc làm | Hiện tại |
|---|---|---|
UA bot (ua_bot) | Loại robot tìm kiếm, trình xem trước, script (curl, python, headless…) và yêu cầu không có User-Agent. | Bật |
Trình duyệt tự động (headless) | Loại trình duyệt bật navigator.webdriver, HeadlessChrome, PhantomJS, Electron, jsdom và yêu cầu không có Accept-Language. Đây là định nghĩa đo lường, không tính là biện pháp chống script. | Bật |
Trạng thái hiển thị và tiêu điểm của tab (visibility_focus) | Lượt hiển thị chỉ đếm khi tab đang hiển thị (document.visibilityState = visible) và cửa sổ có tiêu điểm, thời gian hiển thị chỉ đếm khi tab đang hiển thị. Đây là định nghĩa đo lường. | Bật |
Xác định viewable (min_view) | Phải có ít nhất một tỷ lệ nhất định của mô hình trên màn hình, với diện tích từ một mức nhất định trở lên, kéo dài quá một khoảng thời gian nhất định thì mới là 1 lượt hiển thị. Đây là định nghĩa đo lường. | Bật |
Giới hạn lặp lại theo người và địa chỉ internet (repeat_limit) | Lượt hiển thị và lượt nhấp của cùng người, cùng mô hình chỉ tính một lần trong một khoảng thời gian nhất định; lượt vào (gồm cả đi vào qua cửa) mỗi ngày một lần và tối đa một số lần nhất định trong một số ngày nhất định. Loại phần vượt mức trần mỗi giờ của một nhóm địa chỉ internet, số người xem mới mỗi ngày theo không gian, số lượt hiển thị, nhấp, vào mỗi ngày theo chiến dịch và không gian. Giới hạn lượt vào được kiểm tra lại bằng nhật ký sự kiện của máy chủ nên máy chủ khởi động lại cũng không quên. | Bật |
Token do máy chủ ký (signed_token) | Sự kiện phải mang token đã ký (HMAC) do serve cấp. Người xem và nhóm địa chỉ internet lúc serve được ký vào token; lượt hiển thị đến từ địa chỉ khác bị loại, lượt hiển thị trước khi qua một khoảng thời gian nhất định kể từ serve cũng bị loại. Trong thời hạn hiệu lực, token chỉ tính mỗi loại hiển thị, nhấp, vào một lần. Ngân sách chiến dịch được kiểm tra lại lúc đếm, sự kiện vượt ngân sách không được đếm (budget). | Bật |
Đo thời gian hiển thị (view_time) | Thời gian hiển thị chỉ đếm khi trong khoảng đó có thao tác camera hoặc con trỏ, và chỉ đến mức trần mỗi token, mỗi ngày cho mỗi người và mô hình, mỗi ngày cho mỗi địa chỉ internet và mô hình. | Bật |
Lưu lượng của chính nhà vận hành (owner_traffic) | Sự kiện đến từ địa chỉ internet đã mở trang quản lý của không gian đó bị loại trong một số ngày nhất định. | Bật |
Dấu vết thao tác của người (human_input) | Lượt nhấp chỉ đếm những gì trình duyệt đánh dấu là thao tác của người (isTrusted). Lượt hiển thị không xét số lần thao tác (người xem yên lặng, người dùng bàn phím và trình đọc màn hình). | Bật |
Giám sát bất thường và tạm giữ (anomaly) | Lượt hiển thị một người xem vượt một số nhất định mỗi ngày bị loại. Lượt nhấp và lượt vào CPA được đếm đến mức tự động công nhận mỗi ngày theo không gian, phần vượt bị tạm giữ. Nếu tỷ lệ nhấp và vào (so với mạng lưới không tính không gian đó), lượt hiển thị trên mỗi lượt nhấp không gian, người xem mới trên mỗi địa chỉ internet, tỷ trọng trung tâm dữ liệu, lặp lại từ cùng địa chỉ, lượt vào trên mỗi lượt nhấp vượt ngưỡng, phần của không gian đó trong tháng đó bị tạm giữ và quản trị viên quyết định. | Bật |
Mạng trung tâm dữ liệu (asn) | Nếu x-mm-asn (số AS) do Cloudflare gắn là mạng đám mây hoặc lưu trữ thì sự kiện bị loại, tỷ trọng đó lớn thì không gian bị tạm giữ. Chỉ tin khi header bí mật (origin-auth) mà Cloudflare Transform Rule gắn kèm khớp với giá trị env của máy chủ; nếu không thì mạng của sự kiện đó ghi là 「không rõ」 và tỷ trọng trung tâm dữ liệu chỉ đo bằng các sự kiện biết mạng. | Bật |
Xác minh người thật khi vào (turnstile) | Lượt vào không gian thương hiệu (/ads/go) phải qua Cloudflare Turnstile trên tên miền Metamoa mới được đếm. Dù thất bại, người dùng vẫn được chuyển sang không gian thương hiệu, chỉ là không đếm lượt vào. Lượt vào khi chưa có khóa bị tạm giữ. | Bật |
Xác minh người thật cho lượt hiển thị (turnstile_imp) | SDK chạy Cloudflare Turnstile trong một cửa sổ metamoa ẩn và gắn thẻ thông hành nhận được (gắn với mạng và không gian đó) vào lượt hiển thị. Có thẻ thì được tính; xác minh thất bại thì bị loại. Không có thẻ thì chỉ lượt đó bị tạm giữ; hết tháng sẽ được giải phóng hoặc hủy theo tỷ lệ không xác minh được của không gian (quản trị viên có thể giải phóng). Quảng cáo luôn hiển thị như bình thường. | Bật |
- Lượt nhấp và lượt vào chỉ được đếm khi lượt hiển thị của token đó đã được đếm trước (nếu không là no_impression).
- Khi bảng máy chủ ghi nhớ đã đầy, máy chủ không xóa bản ghi còn hạn mà ngừng đếm sự kiện mới (capacity). Đóng theo hướng chặn.
Quy cách sự kiện
Yêu cầu SDK chỉ được nhận từ trang của chính không gian đó. Nếu là tên miền riêng của nhà vận hành thì phải cùng tên miền đăng ký, nếu là máy chủ dùng chung như github.io, vercel.app thì tên máy chủ phải giống hệt, còn không gian nằm dưới một đường dẫn (github.io/<kho>, claude.ai) thì đường dẫn Referer cũng phải nằm dưới đó (SDK gửi Referer đầy đủ). Tất cả mở CORS, JSON. Cũng nhận sendBeacon (text/plain).
Nhận quảng cáo · 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"
}
]
}
}
Nếu ad là null thì hiện chưa có quảng cáo để chạy ở vị trí đó. Nếu kind là model thì đặt glb của model_url; nếu là building thì đặt glb tòa nhà, sau đó nếu mode là image thì dán ảnh image_url lên tên mesh trong faces, nếu là texture thì dán image_url lên toàn bộ texture.meshes, lặp theo repeat. Nếu là character thì dựng glb nhân vật, gắn đạo cụ vào vị trí prop.attach rồi đặt ảnh image_url hoặc chữ của text lên tấm bảng đó. Tất cả đều khớp với hộp slot.size nhưng chỉ phóng to thu nhỏ trong hệ số slot.scale so với kích thước gốc.
Đăng ký vị trí · 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 (같은 이름의 자리를 바꾸지 않고 그대로)
Gửi sự kiện · 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 | Trường | Ý nghĩa |
|---|---|---|
| imp | token, ms, area, inside, vis, focus, inputs, wd | ms: thời gian hiển thị liên tục, area: diện tích mô hình so với diện tích màn hình (0~1), inside: phần mô hình nằm trong màn hình (0~1), vis·focus: tab hiển thị và cửa sổ có tiêu điểm, inputs: số lần thao tác camera và con trỏ trong thời gian đó, wd: navigator.webdriver |
| time | token, ms, vis, inputs, wd | Thời gian hiển thị kể từ lần time trước (tối đa 15,000ms) và số lần thao tác trong khoảng đó |
| click | token, trusted, wd | Đã chạm hoặc nhấp vào quảng cáo. trusted: thao tác của người (isTrusted) |
Lượt hiển thị được tính cùng thẻ xác minh người thật mà SDK nhận từ một cửa sổ metamoa ẩn (Cloudflare Turnstile). Quảng cáo hiện ngay, không chờ thẻ. Nếu trang của bạn gửi Content-Security-Policy, hãy thêm https://metamoa.com vào frame-src. Khi cửa sổ bị chặn hoặc không có thẻ, lượt hiển thị đó bị tạm giữ; sau khi hết tháng sẽ được giải phóng nếu tỷ lệ không xác minh được của không gian từ 20% trở xuống, và bị hủy nếu vượt quá.
Mỗi lần tối đa 20 cái. Sự kiện không gửi vid. Người xem lấy theo giá trị trong token. Sự kiện sai và token của không gian khác chỉ được đếm là excluded.
Lượt vào · go
Lượt vào chỉ được đếm sau khi /ads/go trên tên miền Metamoa xác minh bằng Cloudflare Turnstile rằng đó là người thật (khi có khóa, một màn hình xác minh nhỏ hiện trong 1~2 giây). Dù xác minh thất bại, người đó vẫn đi tới không gian thương hiệu, chỉ là không đếm lượt vào.
GET https://metamoa.com/ads/go?t={serve 토큰}
→ 302 Location: {brand_url} (노출이 센 토큰이면 입장을 센 뒤 브랜드 공간으로. 캠페인이 집행 중·기간 안이고 토큰이 유효 시간 안일 때만 검수에서 승인된 brand_url로 가고, 아니면 Location: /)Tòa nhà quảng cáo, nhân vật và quy cách tải lên
Nhà quảng cáo chưa có mô hình chọn tòa nhà quảng cáo hoặc nhân vật quảng cáo cơ bản do chúng tôi cung cấp. Với tòa nhà, chọn một trong hai cách: dạng ảnh (mỗi tấm bảng định sẵn một ảnh) · dạng texture (một texture hoặc họa tiết phủ toàn bộ bề mặt tòa nhà).
Với dạng texture, tải mẫu gốc mặc định (PNG vuông) về, sửa rồi tải lên đúng kích thước đó (1024~2048px). Đường kẻ hồng trên mẫu gốc có đường kẻ là ranh giới các mảnh bề mặt, chỉ tô bên trong mảnh là sẽ hiện trên bề mặt đó.
Cửa hàng quảng cáo (shop-ad) hiển thị một ảnh đã tải lên ở mặt trước, hai bên, mặt sau và mặt trên: biển phía trước, hai bên, phía sau và tấm bảng trên mái đều cùng tỷ lệ, nên nhìn từ phía nào, kể cả nhìn từ trên xuống, cũng đọc được. Có cửa nên dùng được 「Đi vào qua cửa」 ("door": true).
Nhân vật quảng cáo cơ bản miễn phí với mọi mức chi. Chúng đứng hoặc đi lại ở vị trí character, cầm các đạo cụ gắn vào xương như biển đeo cổ, thẻ nhân viên, bảng cầm tay, bóng bay, cờ, túi mua sắm, và tấm bảng đạo cụ chứa ảnh quảng cáo hoặc chữ biển hiệu (tối đa 12 ký tự). Mèo, chó và Vincent chỉ dùng được đạo cụ đeo ở cổ.
| Nhân vật | id | Đạo cụ có thể cầm | Giấy phép |
|---|---|---|---|
| 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 | Tự làm (FLOAT Co., Ltd.) |
| Mèo lông ngắn Nyangjupgo | cat_short | prop-neck-sign prop-badge | CC BY 4.0 |
| Mèo lông dài Nyangjupgo | cat_long | prop-neck-sign prop-badge | CC BY 4.0 |
| Mèo Munchkin Nyangjupgo | cat_munchkin | prop-neck-sign prop-badge | CC BY 4.0 |
| Chó Corgi Nyangjupgo | dog_corgi | prop-neck-sign prop-badge | CC BY 4.0 |
| Đạo cụ | id | Tỷ lệ ảnh · kích thước tối thiểu |
|---|---|---|
| Biển đeo cổ (kiểu thẻ nhân viên) | prop-badge | 720:1024, từ 360×512px trở lên |
| Bóng bay | prop-balloon | 1024:1024, từ 512×512px trở lên |
| Cờ cầm tay | prop-flag | 1024:688, từ 512×344px trở lên |
| Biển đeo ở cổ | prop-neck-sign | 1024:720, từ 512×360px trở lên |
| Bảng cầm tay | prop-picket | 1024:720, từ 512×360px trở lên |
| Túi mua sắm | prop-shopping-bag | 1024:1024, từ 512×512px trở lên |
- Định dạng ảnh: PNG · JPEG · WEBP, tối đa 2MB, chiều ngang và dọc tối đa 4096px, sai số tỷ lệ tối đa 2%. Ảnh tải lên được lưu lại dưới dạng WebP (thông tin ảnh bị xóa).
- Mô hình 3D: một tệp nhị phân glTF 2.0 (.glb), tối đa 6MB, texture nằm trong tệp, không có địa chỉ bên ngoài (uri).
- Tệp tải lên được kiểm tra định dạng theo nội dung (magic byte): ảnh chỉ nhận PNG, JPEG, WebP (không nhận SVG, HTML…) và tạo lại thành WebP, mô hình chỉ nhận nhị phân glTF 2.0. Tệp quảng cáo chỉ được phát với kiểu cố định (image/webp, model/gltf-binary), nosniff và chính sách sandbox nên không bao giờ chạy như script.
- Kích thước mô hình quảng cáo có thể được nhà vận hành không gian hoặc Metamoa điều chỉnh tùy theo không gian.
- Tệp mô hình và nhân vật nằm dưới /ads/models/ và chỉ được phát bằng phản hồi không cho phép script (kiểu cố định, nosniff, sandbox). Danh sách và nguồn ở docs/ads/MODELS.md; khi thay đổi, dùng scripts/ads-import-models.mjs để tạo lại cùng lúc data/ads-buildings.json và các tệp.
Ghi nguồn mô hình
Phần lớn mô hình cơ bản là CC0 (phạm vi công cộng) hoặc tự làm; các mô hình dưới đây là CC BY nên ghi rõ nguồn. Tất cả đều được FLOAT Co., Ltd. chỉnh sửa kích thước, mặt quảng cáo…
- Biển quảng cáo đứng: "Blank Billboard" by Jarlan Perez (https://poly.pizza/m/1E0d2B7bC8e), CC BY 3.0 (https://creativecommons.org/licenses/by/3.0/), FLOAT Co., Ltd. chỉnh sửa
- Gian hàng pop-up: "Carnival Booth" by sirkitree (https://poly.pizza/m/4NizXJZsuO2), CC BY 3.0 (https://creativecommons.org/licenses/by/3.0/), FLOAT Co., Ltd. chỉnh sửa
- Biển quảng cáo trạm xe buýt: "Bus Stop" by Zsky (https://poly.pizza/m/OWczicNWhO), CC BY 3.0 (https://creativecommons.org/licenses/by/3.0/), FLOAT Co., Ltd. chỉnh sửa
- Biển chữ 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. chỉnh sửa
- Mèo lông ngắn Nyangjupgo: "Cat" by Polyfork (https://polyfork.dev/asset/cat-base), CC BY 4.0, FLOAT Co., Ltd. chuyển thành voxel
- Mèo lông dài Nyangjupgo: "Cat" by Polyfork (https://polyfork.dev/asset/cat-base), CC BY 4.0, FLOAT Co., Ltd. chuyển thành voxel
- Mèo Munchkin Nyangjupgo: "Cat" by Polyfork (https://polyfork.dev/asset/cat-base), CC BY 4.0, FLOAT Co., Ltd. chuyển thành voxel
- Chó Corgi Nyangjupgo: "Dog" by Polyfork (https://polyfork.dev/asset/dog-base), CC BY 4.0, FLOAT Co., Ltd. chuyển thành voxel
Yêu cầu làm mô hình
Khi nhà quảng cáo chọn 「Yêu cầu làm mô hình」, chúng tôi làm mô hình 3D, gắn vào chiến dịch rồi duyệt. Hãy gửi tư liệu (ảnh sản phẩm, logo, bản vẽ) đến [email protected] kèm mã chiến dịch.
| Hạng | grade | Phí làm | Miễn phí nếu chi từ mức phí truyền thông này trở lên |
|---|---|---|---|
| Sản phẩm đơn giản · biển hiệu | simple | ₩50,000 (giá chưa thuế, chưa gồm VAT) | ₩500,000 |
| Sản phẩm chi tiết | precise | ₩100,000 (giá chưa thuế, chưa gồm VAT) | ₩1,000,000 |
| Nhân vật mới | character | ₩100,000 (giá chưa thuế, chưa gồm VAT) | ₩1,000,000 |
- Mức miễn phí tính theo phí truyền thông thực chi (tổng toàn bộ thời hạn hợp đồng, tối đa 3 tháng, không tính phí dựng mô hình, VAT và lưu lượng không hợp lệ).
- Mô hình làm miễn phí chỉ được cấp quyền sử dụng để phát trên Metamoa (bản quyền thuộc Metamoa, chuyển nhượng khi đã trả phí làm), được sửa 1 lần. Nếu nhà quảng cáo tự hủy hoặc giảm mức chi, phí làm được tính theo tỷ lệ: phí làm × (1 − phí truyền thông thực chi ÷ mức miễn phí). Mô hình trả phí được sửa 2 lần.
- Nhân vật quảng cáo cơ bản (nhân vật của Trại Moa và Nyangjupgo) dùng miễn phí với mọi mức chi, không cần yêu cầu làm.
Nhà quảng cáo: các bước tự đăng ký
- Đăng nhập bằng tài khoản Metamoa tại https://metamoa.com/ads/manage (đăng ký cũng trong cùng cửa sổ).
- Tạo chiến dịch: tên, thương hiệu, ngành, địa chỉ không gian thương hiệu (khi dùng CPA lượt vào).
- Tư liệu quảng cáo: ① tải lên mô hình 3D của mình (glb) ② chọn tòa nhà quảng cáo → dạng ảnh thì mỗi tấm bảng một ảnh, dạng texture thì một texture ③ chọn nhân vật quảng cáo cơ bản + đạo cụ → ảnh hoặc chữ biển hiệu trên tấm bảng đạo cụ ④ yêu cầu làm mô hình (chọn hạng). Quy cách và bản xem trước sẽ hiện ra.
- Không gian hiển thị: từ danh sách không gian đã đồng ý hiển thị quảng cáo, xem danh mục, số người đang truy cập và lượt nhấp không gian mỗi ngày rồi tự chọn vị trí, hoặc bấm 「Gợi ý」 để nhận một nhóm không gian phù hợp ngành, danh mục và lưu lượng.
- Chọn cách tính phí (CPM, CPA, thời gian hiển thị, hợp đồng vị trí cố định), ngân sách và thời gian rồi đăng ký → chờ duyệt.
- Qua được kiểm duyệt (khiêu dâm, bạo lực, nghi vi phạm bản quyền…) thì sẽ chạy. Chiến dịch đang chạy có thể tạm dừng và bật lại, và bạn xem lượt hiển thị viewable, lượt nhấp, lượt vào, thời gian hiển thị theo từng ngày.
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>)
Tư liệu nhân vật: {"kind": "character", "character_id": "bangjang", "prop": "prop-picket", "image": "as_…"} hoặc "text": "Sữa Lấp Lánh" thay cho "image". Hợp đồng vị trí cố định: "billing": "fixed", "fixed_period": "week" | "month", end_day = start_day + thời hạn − 1. Yêu cầu làm mô hình: {"kind": "request", "grade": "simple", "note": "…"}.
Tư liệu tòa nhà và mô hình riêng có thể thêm hai thứ (tùy chọn): "tagline": "mô tả một dòng" (tối đa 30 ký tự, chỉ chữ — không dùng thẻ, dấu ngoặc nhọn hay ngoặc móc (400 invalid, fields creative), được duyệt cùng tư liệu) được vẽ trên dải dưới biển hiệu của cửa hàng quảng cáo hoặc tòa nhà (mesh ad_tagline), và trả về qua ad.tagline { text, mesh, aspect } của serve. "door": true là 「Đi vào qua cửa」 (cần brand_url). Giống ô 「Mô tả một dòng」 và 「Đi vào qua cửa」 ở bước 2 của /ads/manage.
Kiểm duyệt
- Mô hình, ảnh và chiến dịch đã tải lên ở trạng thái chờ duyệt (review) trước khi chạy. Quản trị viên duyệt thì chạy (active), từ chối thì lưu lại rejected kèm lý do.
- Ảnh được kiểm tra trước bằng AI khi tải lên để phát hiện khiêu dâm, bạo lực, logo hay nhân vật của người khác, vướng là chặn ngay (rejected). Nếu không kiểm tra được thì quản trị viên trực tiếp xem.
- Mô hình do quản trị viên trực tiếp mở xem. Nếu khiêu dâm, bạo lực hoặc nghi vi phạm bản quyền thì từ chối.
Mã lỗi
Nội dung lỗi là { "error": "<mã>", "message": "<một dòng về việc cần làm tiếp>" }, lỗi trường đi kèm fields, giới hạn đi kèm retry_after.
| HTTP | error | Ý nghĩa |
|---|---|---|
| 400 | invalid | Định dạng trường sai. fields chứa các trường sai. |
| 400 | bad_model | Không phải glb, không phải glTF 2.0, hoặc có địa chỉ bên ngoài (uri). Lý do ở reason. |
| 400 | bad_image | Định dạng, kích thước hoặc tỷ lệ ảnh khác quy cách. Trả về reason (format · bytes · too_large · too_small · aspect) và spec. |
| 400 | bad_building | default_building của vị trí không phải id tòa nhà hoặc biển của GET /ads/v1/buildings (để trống thì được). |
| 400 | slot_unavailable | Vị trí đã chọn không nhận quảng cáo, không nhận ngành đó, hoặc không hợp với loại tư liệu (nhân vật chỉ ở vị trí nhân vật). slot_ids chứa các vị trí đó. |
| 401 | unauthorized | Không có hoặc sai khóa không gian, đăng nhập trang quản lý không gian. |
| 401 | sign_in | Nhà quảng cáo: chưa đăng nhập tài khoản Metamoa hoặc đã hết hạn. |
| 403 | owner_required | Có khóa không gian nhưng chưa xác nhận nhà vận hành không gian. |
| 403 | owner_page_only | Thử xác nhận điều khoản hoặc đồng ý hiển thị quảng cáo bằng khóa không gian (chỉ làm được trong trang quản lý không gian). |
| 403 | bad_ad_key | SDK: space và key (mm_adpub_) không khớp. |
| 403 | terms_required | Không gian đó chưa xác nhận điều khoản hiển thị quảng cáo. |
| 403 | ads_off | Không gian đó đã tắt đồng ý hiển thị quảng cáo. |
| 403 | origin_mismatch | Yêu cầu SDK không đến từ trang của không gian đó (cùng tên miền). |
| 404 | not_house | Gọi quảng cáo của chúng tôi (GET /ads/v1/house) từ nơi không phải không gian do Metamoa trực tiếp vận hành. |
| 403 | not_yours | Nhà quảng cáo: dùng id tệp của người khác. |
| 404 | no_slot | Không có vị trí quảng cáo với tên hoặc id đó. |
| 404 | not_found | Không có chiến dịch hoặc tệp đó. |
| 409 | not_listed | Không gian chưa được đưa vào danh sách (trước khi duyệt hoặc đã ẩn). |
| 409 | payout_info_required | Muốn bật đồng ý hiển thị quảng cáo nhưng chưa có loại thông tin thanh toán (cá nhân, doanh nghiệp) và liên hệ (điện thoại di động hoặc email). Nhập trong mục Kiếm tiền của trang quản lý không gian (/owner/revenue?id=<id không gian>). |
| 409 | advertiser_required | Nhà quảng cáo: định đăng ký hoặc thanh toán chiến dịch trước khi nhập thông tin nhà quảng cáo (PUT /api/ads/advertiser). |
| 409 | biz_doc_required | Nhà quảng cáo: nhà quảng cáo doanh nghiệp thanh toán hoặc đăng ký hợp đồng vị trí cố định trước khi tải lên bản sao giấy đăng ký kinh doanh (PUT /api/ads/advertiser/doc). |
| 409 | business_only | Nhà quảng cáo: nhà quảng cáo cá nhân định tải lên bản sao giấy đăng ký kinh doanh. |
| 400 | bad_doc | Nhà quảng cáo: bản sao giấy đăng ký kinh doanh không phải PDF, JPG, PNG. |
| 413 | doc_too_big | Nhà quảng cáo: bản sao giấy đăng ký kinh doanh vượt quá 5MB. |
| 503 | advertiser_unavailable | Nhà quảng cáo: máy chủ không có khóa mã hóa thông tin nhà quảng cáo nên không nhận được. |
| 409 | email_not_linked | Nhà quảng cáo: email của nhà quảng cáo cá nhân không phải email đã đăng nhập tài khoản Metamoa này. |
| 409 | name_taken | Đã có vị trí cùng tên. |
| 409 | slot_limit | Mỗi không gian tối đa 30 vị trí của nhà vận hành, tối đa 5 vị trí SDK chưa xác nhận. |
| 409 | slot_taken | Vị trí đã có hợp đồng vị trí cố định khác trong thời gian đó. |
| 409 | tier_too_low | Chọn theo hợp đồng vị trí cố định một vị trí ở không gian có lượt nhấp không gian mỗi ngày chưa đạt hạng thấp nhất. slot_ids chứa các vị trí đó. |
| 409 | not_for_sale | Không có đơn giá hợp đồng vị trí cố định. |
| 409 | under_minimum | Thấp hơn mức phí truyền thông tối thiểu. Trả về min_spend_won, spend_won. |
| 409 | no_click_history | Chọn CPM hoặc hợp đồng vị trí cố định cho vị trí ở không gian chưa có lịch sử lượt nhấp không gian (không đo được lượng hiển thị và hạng). Chỉ được chọn CPA và thời gian hiển thị. Trả về slot_ids, billings. |
| 409 | over_inventory | Ngân sách CPM vượt mức trần lượt hiển thị viewable dự kiến của các vị trí đã chọn. Trả về max_budget_won. |
| 409 | rejected_file | Dùng trong chiến dịch tệp đã bị chặn khi kiểm duyệt. |
| 409 | wrong_state | Việc không làm được ở trạng thái đó (tạm dừng chiến dịch đang duyệt…). |
| 409 | stale | Quản trị viên: chiến dịch đã thay đổi sau khi mở màn hình duyệt (version của decide khác hiện tại). Xem lại rồi quyết định lại. |
| 409 | already_paid | Định mở lại thanh toán cho chiến dịch đã thanh toán. |
| 409 | not_paid | Quản trị viên: định duyệt quyết toán cho chiến dịch chưa thanh toán xong. |
| 409 | held | Quản trị viên: định duyệt quyết toán cho chiến dịch còn phần đang tạm giữ (hãy quyết định phần tạm giữ trước). |
| 424 | hrum_failed | Không kết nối được thanh toán (Hrum). Vui lòng thử lại sau ít phút. |
| 503 | pay_not_ready | Chưa mở được thanh toán (máy chủ chưa thiết lập). |
| 409 | model_missing | Quản trị viên: duyệt chiến dịch yêu cầu làm mô hình trước khi gắn mô hình. |
| 413 | model_too_big | Tệp mô hình vượt quá 6MB. |
| 429 | too_many | Quá nhiều yêu cầu. Hãy chờ số giây ở Retry-After. |
Toàn bộ đường dẫn
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