제작자 SDK 설치 가이드

태그 한 줄로 실시간 승객 수가 표시되고, 같은 태그가 사이트 소유 증명이 돼요. 등록 화면의 스니펫을 복사해 아래 규칙대로 넣어 주세요.

속성	값	설명
data-badge	bottom-right \| bottom-left \| top-right \| top-left \| none	라이브 배지 위치. 기본은 bottom-right, none이면 배지를 숨겨요.
data-badge-link	on \| off	off면 배지를 눌러도 metabus.app으로 이동하지 않아요. 기본 on.
data-lang	ko \| en	en이면 배지 문구가 영어로 나와요. 그 외 값은 한국어.

설치 규칙

등록한 URL이 서버에서 보내는 HTML의 <head> 안에 정적으로 넣어요.
useEffect·document.createElement·태그 매니저·Next.js App Router의 next/script처럼 실행 중에 넣는 방식은 검증을 통과하지 못해요(TAG_NOT_FOUND). 검증기는 JavaScript를 실행하지 않고 HTML만 읽어요.
<body>·주석·<template>·<noscript> 안에는 넣지 않아요.
src 주소를 바꾸거나 쿼리를 붙이거나 파일을 직접 호스팅하지 않아요.
공통 레이아웃이 있으면 그곳에 한 번만 넣어요.

확인 방법

배포된 주소에서 "페이지 소스 보기"(view-source:)를 열어 <head> 안에 태그가 있는지 확인하세요. 개발자 도구 Elements 패널이 아니라 원본 소스에 있어야 해요.

프레임워크별 위치

HTML · GitHub Pages

등록 URL이 가리키는 index.html의 <head> 안에 넣어요.

<!-- index.html: <head> 안에 정적으로 -->
<head>
  <meta charset="utf-8" />
  <script src="https://sdk.metabus.app/presence.v1.js" data-site="mb_S000000000_example" async></script>
</head>

Vite

프로젝트 루트의 index.html <head> 안에 넣어요.

<!-- index.html (project root): <head> 안에 정적으로 -->
<head>
  <meta charset="utf-8" />
  <script src="https://sdk.metabus.app/presence.v1.js" data-site="mb_S000000000_example" async></script>
</head>

Create React App

public/index.html의 <head> 안에 넣어요.

<!-- public/index.html: <head> 안에 정적으로 -->
<head>
  <meta charset="utf-8" />
  <script src="https://sdk.metabus.app/presence.v1.js" data-site="mb_S000000000_example" async></script>
</head>

Next.js App Router

app/layout.tsx의 <html><head> 안에 일반 <script> 엘리먼트를 직접 써요. next/script는 App Router에서 정적 태그를 만들지 않아 TAG_NOT_FOUND로 실패해요.

// app/layout.tsx
export default function RootLayout({ children }: { children: React.ReactNode }) {
  return (
    <html lang="ko">
      <head>
        <script src="https://sdk.metabus.app/presence.v1.js" data-site="mb_S000000000_example" async />
      </head>
      <body>{children}</body>
    </html>
  );
}

Next.js Pages Router

pages/_document.tsx의 <Head> 안에 넣어요. 여기서는 next/script strategy="beforeInteractive"도 괜찮아요.

// pages/_document.tsx
import { Head, Html, Main, NextScript } from 'next/document';
import Script from 'next/script';

export default function Document() {
  return (
    <Html lang="ko">
      <Head>
        <Script src="https://sdk.metabus.app/presence.v1.js" data-site="mb_S000000000_example" strategy="beforeInteractive" />
      </Head>
      <body>
        <Main />
        <NextScript />
      </body>
    </Html>
  );
}

그 밖의 SSR · 정적 사이트 생성기

최종 HTML의 <head>를 만드는 레이아웃·템플릿 파일에 넣어요.

SRI 고정 버전

integrity 해시로 고정하려면 presence.v1.<버전>.js 주소와 integrity·crossorigin 속성을 함께 써요. 고정 버전은 자동 패치를 받지 못해요. 버그·보안 수정은 버전과 해시를 직접 바꿔야 반영돼요.

AI 코딩 도구로 설치하기

등록 화면의 "AI 프롬프트" 탭을 복사해 Cursor·Claude Code 같은 도구에 붙여 넣으면 위 규칙대로 설치를 맡길 수 있어요. 기계가 읽는 설치 규칙은 metabus.app/llms.txt에 있어요.

기계용 설치 규칙(llms.txt)

검증 실패 사유

"다시 확인"이 실패하면 아래 사유 중 하나가 표시돼요.

TAG_NOT_FOUND

태그를 찾지 못했어요

HTML 원본에 태그가 없어요. 실행 중에 넣는 방식(useEffect·태그 매니저·App Router next/script)을 빼고 head 영역에 정적으로 넣은 뒤 다시 배포해 주세요.

TAG_IN_BODY

태그가 body에 있어요

태그를 head 영역으로 옮겨 주세요.

SITE_ID_MISMATCH

site id가 달라요

data-site 값이 이 등록의 site id와 달라요. 등록 화면의 태그를 다시 복사해 주세요.

REDIRECT_OFF_DOMAIN

다른 도메인으로 이동해요

등록 주소가 다른 도메인으로 리다이렉트돼요. 최종 주소로 등록하거나 리다이렉트를 없애 주세요.

UNREACHABLE

주소가 열리지 않아요

로그인 없이 공개로 열리고 HTML을 15초 안에 돌려주는지 확인해 주세요.

도저히 넣을 수 없을 때

호스팅이 <head> 수정을 허용하지 않는 등 규칙을 지킬 수 없으면, 검증 실패 기록이 남은 뒤 등록 화면에서 운영자 수동 확인을 요청할 수 있어요.

제작자 고지 — 방문자 데이터

SDK는 내 사이트의 localStorage(차단 시 sessionStorage)에 무작위 방문자 id(mb_vid, UUID)를 저장해요. 이 값은 내 사이트 origin 안에만 있고, 실시간 승객 수 집계를 위하여 metaBus로 전송돼요.

들어올 때 이전 페이지의 origin(도메인)만 함께 보내며 경로·쿼리는 보내지 않아요. 쿠키를 만들지 않고 제3자 분석 스크립트를 불러오지 않아요.

내 사이트의 개인정보 처리방침에 "방문자 수 집계를 위해 metaBus(metabus.app)가 무작위 식별자를 브라우저 저장소에 저장한다"는 내용을 안내하는 것을 권장해요.

태그

선택 속성