# metaBus

> metaBus (https://metabus.app) is a directory of browser-playable online spaces. Creators register a space by adding one static script tag (the Presence SDK). The tag is both the live-visitor counter and the proof of site ownership.

This file tells AI coding agents how to install the metaBus Presence SDK correctly. Human guide: https://metabus.app/guide/sdk (Korean) · https://metabus.app/en/guide/sdk (English).

## The tag

```html
<script src="https://sdk.metabus.app/presence.v1.js" data-site="SITE_ID" async></script>
```

- `SITE_ID` is the public id shown on the registration page (format `mb_<uid>_<suffix>`). Copy it exactly.
- Optional attributes: `data-badge` = `bottom-right` (default) | `bottom-left` | `top-right` | `top-left` | `none`; `data-badge-link` = `on` (default) | `off`; `data-lang` = `ko` (default) | `en`. Any other `data-*` is ignored.
- SRI-pinned variant: `https://sdk.metabus.app/presence.v1.<semver>.js` with `integrity` and `crossorigin="anonymous"`. It never receives automatic patches.

## Install rules (must follow)

1. Put the tag statically inside `<head>` of the HTML document the server returns for the registered URL.
2. Never inject it at runtime (`useEffect`, `componentDidMount`, `document.createElement`, `document.head.appendChild`, tag managers, `next/script` in the Next.js App Router). Verification reads the raw HTML without executing JavaScript, so runtime injection fails with `TAG_NOT_FOUND` even though the SDK itself runs.
3. Do not put it inside `<body>`, HTML comments, `<template>` or `<noscript>`.
4. Do not change the `src` URL, add a query string, or self-host/bundle the file. The `src` must be exactly one of the two URLs above.
5. Keep `data-site` identical to the id from the registration page.
6. Add it once, in the shared layout/template if there is one.
7. The page must answer with `text/html` on the registered URL, within 15 seconds, with `<head>` inside the first 2 MB, and any redirect must stay on the registered domain. Query strings are removed from registered URLs.

## Where to put it

| Stack | File | Placement |
|---|---|---|
| Plain HTML, GitHub Pages | `index.html` served at the registered URL | inside `<head>` |
| Vite (any framework) | `index.html` in the project root | inside `<head>` |
| Create React App | `public/index.html` | inside `<head>` |
| Next.js App Router | `app/layout.tsx` | plain `<script src=... data-site=... async />` inside `<html><head>`; do not use `next/script` |
| Next.js Pages Router | `pages/_document.tsx` | inside `<Head>`; `next/script` with `strategy="beforeInteractive"` is fine |
| Other SSR / static site generators | the layout or template that renders the final `<head>` | inside `<head>` |

Check: open `view-source:` on the deployed URL. The tag must be inside `<head>` in the raw source, not only in the DevTools Elements panel.

## Verification failure codes

| Code | Meaning | Fix |
|---|---|---|
| `TAG_NOT_FOUND` | No tag with the exact SDK `src` in the fetched HTML. Typical cause: runtime injection by a SPA, a tag manager or `next/script` (App Router); also a changed `src`, a query string, or a page that was not redeployed. | Add the tag statically to the file in the table above, deploy, then press "Check again". |
| `TAG_IN_BODY` | The tag exists but is inside `<body>`. | Move it into `<head>`. |
| `SITE_ID_MISMATCH` | A tag is in `<head>` but `data-site` differs from this registration's site id (old id, another space's id, or a typo). | Copy the site id from the registration page again. |
| `REDIRECT_OFF_DOMAIN` | The registered URL redirects to a different registrable domain. | Register the final URL, or remove the cross-domain redirect. |
| `UNREACHABLE` | The URL did not return HTML in time (DNS/TLS error, timeout, non-2xx status, non-HTML content type, or a login/maintenance wall). | Make the registered URL publicly reachable without login and returning `text/html`, then check again. |

If the rules cannot be met (for example the host does not allow editing `<head>`), the creator can request manual issuance from the registration page.

## Data the SDK sends

- A random visitor id `mb_vid` (UUID v4) stored in the space's own `localStorage` (falls back to `sessionStorage`); it never leaves that origin except in beacons to `api.metabus.app`.
- Beacons `{site, v, t, sv}` on enter, heartbeat and leave; on enter, the referrer origin only (no path or query).
- The SDK sets no cookies and loads no third-party analytics. The only global is `window.Metabus = { count, on(event, cb) }` with events `count`, `ready`, `error`.

## 한국어 요약

- 태그는 등록 URL이 반환하는 HTML의 **`<head>` 안에 정적으로** 넣는다. `useEffect`·`document.createElement`·태그 매니저·App Router `next/script` 등 런타임 주입은 검증기가 JavaScript를 실행하지 않으므로 `TAG_NOT_FOUND`로 실패한다.
- `src`는 `https://sdk.metabus.app/presence.v1.js`(또는 SRI 변형 `presence.v1.<semver>.js`)와 정확히 일치해야 하고, `data-site`는 등록 화면의 site id 그대로 둔다.
- 위치: 순수 HTML·GitHub Pages `index.html` / Vite 루트 `index.html` / CRA `public/index.html` / Next.js App Router `app/layout.tsx`의 `<head>`(일반 `<script>`) / Pages Router `pages/_document.tsx`.
- 실패 코드: `TAG_NOT_FOUND`(정적 태그 없음) · `TAG_IN_BODY`(`<body>`에 있음) · `SITE_ID_MISMATCH`(site id 불일치) · `REDIRECT_OFF_DOMAIN`(다른 도메인으로 리다이렉트) · `UNREACHABLE`(HTML 응답 실패). 해결 후 "다시 확인".