웹사이트에 측정 넣기

웹사이트나 웹앱에 allob 웹 SDK 를 넣는 방법이에요. 마치면 방문자의 행동이 allob 에 쌓이고, 원하면 Meta 픽셀·GA4·TikTok 에도 같은 이벤트가 전송돼요.

시작하기 전에 첫 제품 연결하기의 1~2단계(제품 만들기, 코드 폴더 연결하기)를 마쳐 주세요.

#에이전트에게 맡기기

https://allob.app/docs/web.md 를 읽고 이 웹사이트에 allob 웹 SDK 를 넣어 줘.
1. allob.json 의 "sdk" 에서 web 경로가 이 프로젝트의 웹 코드 폴더 안을 가리키는지 확인하고, 아니면 고쳐.
2. allob sdk pull 로 SDK 를 받아.
3. 앱이 시작될 때 build() 를 한 번 부르고, 스키마의 이벤트가 일어나는 곳에서 track 함수를 불러.
4. allob 제품에 사이트 주소가 없으면 넣어 달라고 알려 줘(사이트 밖 주소·로컬에서는 이벤트가 쌓이지 않게). 미리보기 주소나 다른 도메인에서도 측정해야 하면 스키마 tracking.allowedHosts 에 넣어.
끝나면 바꾼 파일과 각 이벤트를 보내는 위치를 알려 줘.

에이전트가 하는 일을 아래에 단계별로 적었어요. 에이전트가 이 페이지를 읽고 따라 하니까, 결과를 확인할 때 참고하세요.

#SDK 받기

allob sdk pull

SDK 는 npm 패키지가 아니라, 스키마로 만든 TypeScript 파일이에요. allob.json 의 "sdk" 에 적은 web 폴더에 들어가요. 처음에는 allob/ 이고, 웹 코드가 하위 폴더에 있으면 그 안으로 바꿔요.

{
  "version": 2,
  "account": "my-studio",
  "product": "diary",
  "sdk": { "web": "web/src/allob" }
}

경로는 allob.json 이 있는 폴더를 기준으로 적고, 그 폴더 밖은 가리킬 수 없어요. 아래 표의 allob/ 은 이 폴더를 말해요.

결제 알림을 받는 서버 코드(server.ts)는 "sdk" 에 server 경로를 추가하면 함께 받아요. 결제 기록하기를 참고하세요.

TypeScript 가 .ts 확장자 import 에서 에러를 내면 tsconfig.json 에 "allowImportingTsExtensions": true 와 "noEmit": true 를 넣어요. Vite, esbuild, Bun 은 설정 없이 동작해요.

#이벤트 보내기

import { build } from "./allob/index.ts";

export const analytics = build({ allowedHosts: ["diary.example.com"] });

analytics.track.entryWrite({ mood: "good" });
analytics.track.checkoutStart({ plan: "yearly", price: 39 });
analytics.trackOnce.paywallView({ from: "limit" });   // 같은 페이지에서 같은 값이면 한 번만

• 이벤트 함수 이름은 스키마의 이벤트 이름을 카멜 표기로 바꾼 거예요(checkout_start → checkoutStart).
• 측정 코드에서 에러가 나도 화면은 멈추지 않아요. 서버 렌더링처럼 브라우저가 아닌 곳에서는 아무 일도 하지 않아요.
• 이벤트는 allob 수집 주소로 바로 전송돼요. 사이트에 따로 설정할 것은 없어요.

표준 이벤트는 따로 정의하지 않아도 함수가 있어요.

#build() 옵션

#광고·분석 도구로 보내기

스키마 tracking 에 도구 ID 를 적으면 SDK 가 그 도구를 켜요. 적지 않은 도구의 코드는 아예 포함되지 않아요.

"tracking": {
  "metaPixel": { "id": "1234567890" },
  "tiktokPixel": { "id": "C0XXXXXXXXXX" },
  "ga4": { "measurementId": "G-XXXXXXXXXX" }
}

이벤트마다 pixel·ga·tiktok 에 그 도구의 이벤트 이름을 적어야 그 도구로 전송돼요(스키마 레퍼런스). 결제는 브라우저와 서버가 같은 거래 ID 를 써서 도구에서 한 건으로 합쳐져요.

#자동으로 걸러지는 것

allob 이 이벤트를 받을 때 아래 것은 지표에 넣지 않아요. 제품 설정의 데이터 거르기에서 지난 24시간 동안 무엇을 몇 건 걸렀는지 볼 수 있어요.

어느 사이트에서 왔는지는 브라우저가 보내는 출처(Origin)로 알아요. 출처가 없거나 null 이면(프록시, Referrer-Policy: no-referrer 등) SDK 가 같이 보내는 페이지 주소로 봐요.

• 처음 7일은 세기만 해요. 사이트 주소를 정하거나 바꾸면(또는 tracking.allowedHosts 를 바꾸면) 7일 동안은 다른 사이트에서 온 이벤트를 버리지 않고 데이터 거르기에 "다른 사이트(지금은 세기만)"로 보여 줘요. 실제 서비스 주소가 여기 보이면 7일 안에 사이트 주소나 allowedHosts 를 고쳐 주세요. 그 뒤로는 걸러요.
• 앱 안 웹뷰는 사이트를 보지 않아요. Capacitor·Cordova·React Native WebView 처럼 앱 안에서 웹 SDK 를 쓰면 페이지 주소가 localhost 라서 개발 주소와 같아 보여요. SDK 가 웹뷰인 걸 알려 주고, capacitor://localhost 같은 출처도 앱으로 봐서 개발 주소·다른 사이트 거르기를 하지 않아요. 봇 거르기는 그대로 해요.
• 사이트 주소를 바꿨다면 allob sdk pull 을 다시 실행해 배포하세요. SDK 가 새 주소에서 광고·분석 도구를 켜요.

#내 방문 빼기

내가 사이트를 열어 본 기록이 지표에 섞이지 않게 하는 방법은 두 가지예요.

• allob 에서 빼기(추천): 제품 설정 › 데이터 거르기에서 이 브라우저 빼기를 눌러요. 제품 사이트가 열리면서 이 브라우저를 allob 의 뺀 기기 목록에 넣고, 이후로 아무것도 보내지 않아요. 이미 쌓인 이 브라우저의 지난 이벤트도 지표에서 빠져요. 링크는 30분 안에 한 번만, 브라우저 하나에만 써요. 뺀 기기는 50개까지 둘 수 있어서, 꽉 차면 쓰지 않는 기기를 먼저 지워요.
• 주소로 빼기: 사이트 주소 끝에 ?notrack=1 을 붙여 한 번 열어요. 그 브라우저에서는 이후로 아무것도 보내지 않아요. 다시 측정하려면 ?notrack=0 을 붙여 열어요. 코드에서는 analytics.excludeBrowser() 로 같은 일을 해요.

브라우저 데이터를 지우면 이 표시도 지워져요. 그때는 한 번 더 빼 주세요.

뺀 브라우저에서는 analytics.context() 가 null 이에요. 결제 정보(metadata)에 off: analytics.isOff() 를 같이 넣어 주세요. allob 은 off 가 실린 결제를 매출에는 넣고, 결제 수·전환·광고 도구에서는 빼요. 진짜 돈은 매출이지만 내 결제가 광고 성과를 부풀리면 안 되니까요.

const metadata = { ...(analytics.context() ?? {}), ...(analytics.isOff() ? { off: "1" } : {}) };

#동의 받기

유럽처럼 광고·분석 도구를 켜기 전에 동의를 받아야 하는 지역이 있어요. 스키마 tracking.consent 에 지역별 방식을 적어요.

"tracking": { "consent": { "EEA+UK+CH": "opt-in", "default": "opt-out+gpc" } }

지역은 EU·EEA·EEA+UK+CH·LATAM 묶음, 두 글자 국가 코드, default 를 쓸 수 있어요. opt-in 지역이 있으면 SDK 에 consentOptInCountries 가 생겨요. 방식에 맞게 켜고 끄는 코드는 사이트에 직접 넣어야 해요.

import { build, consentOptInCountries, forgetStoredIds } from "./allob/index.ts";

const needsConsent = consentOptInCountries.has(visitorCountry);
const analytics = build({ toolsAllowed: !needsConsent });

// 동의 창에서 허용을 누르면
analytics.allowTools();
// 측정 자체를 거부하면 이 브라우저에 저장한 값을 지워요
forgetStoredIds();

방문자의 국가는 SDK 가 알 수 없어요. 서버가 페이지에 넣어 주거나(예: Cloudflare 의 cf.country) 따로 알아내야 해요.

#결제를 방문 기록과 연결하기

결제는 결제 서비스의 알림(웹훅)을 받는 서버가 기록해요. 서버가 누가 결제했는지 알 수 있도록, 결제창을 열 때 context() 값을 결제 정보(metadata)에 담아 보내요.

const ctx = analytics.context();   // { sid, us?, uc?, un?, ttclid? }, 측정하지 않는 브라우저면 null
await openCheckout({ plan: "yearly", metadata: { sid: ctx?.sid ?? "", us: ctx?.us ?? "", uc: ctx?.uc ?? "" } });

서버에서 이 값을 그대로 서버 이벤트에 넣으면, 결제가 그 방문자의 퍼널과 유입 경로에 이어져요. 결제 기록하기를 참고하세요.

#개인정보 보호

이름, 이메일 같은 개인정보는 이벤트에 넣지 않아요. 이벤트 값은 누구나 주소를 바꿔서 조작할 수 있으니, 화면에 표시할 때는 항상 이스케이프해요.

사용자가 직접 보내는 의견은 이벤트가 아니라 feedback.send() 로 받아요. 사용자 정보도 같이 보낼 수 있고, allob 의 리뷰·피드백 탭에만 보여요(앱 안 피드백 받기).

URL 에 다시 찾아갈 수 있는 ID 가 들어가는 사이트(예: /r/8f3a… 같은 결과 링크)는 privacyGuard 로 그 부분을 도구에서 가려요. 광고·분석 도구는 페이지 주소를 직접 읽어 가기 때문에, 도구로 나가는 요청에서 그 글자를 :id 로 바꿔요.

import { build, privacyGuard } from "./allob/index.ts";

const rules = {
  toolUrl: (href) => href.replace(/\/r\/[^/?#]+/, "/r/:id"),
  secrets: (href) => [...href.matchAll(/\/r\/([^/?#]+)/g)].map((m) => m[1]),
  ownPath: (path) => path.replace(/^\/r\/[^/]+/, "/r/:id"),
};
const analytics = build({ privacy: privacyGuard(rules) });

#보내기 전에 개인정보 걷기

privacy 는 광고·분석 도구로 가는 요청을 지켜요. allob 으로 가는 이벤트에도 주소나 버튼 이름에 개인정보가 섞일 수 있다면 clean 으로 보내기 전에 걷어요. 이벤트는 내 서버를 거치지 않고 브라우저에서 allob 으로 바로 가기 때문에, 걷는 일은 브라우저에서 해요.

const analytics = build({
  privacy: privacyGuard(rules),
  clean: (item) => ({
    ...item,
    path: String(item.path).replace(/\/r\/[^/]+/, "/r/:id"),
    category: String(item.category ?? "").replace(/\d{4}-\d{2}-\d{2}/g, ":date"),
  }),
});

• item 은 보낼 이벤트 한 건이에요. 경로(path)·들어온 곳(ref)·언어(lang)·utm·속성(category 와 필드 속성)이 들어 있어요.
• 고친 이벤트를 돌려주면 그걸 보내요. null 을 돌려주면 그 이벤트를 보내지 않아요.
• 함수가 오류를 내면 그 이벤트는 보내지 않아요. 걷지 못한 개인정보가 나가지 않게요.
• 이벤트 이름(e)과 이벤트 ID(i)는 바꿀 수 없어요. 글자·숫자·참거짓이 아닌 값은 빠져요.

#앱 안 웹 화면(Capacitor)에서 도구까지

Capacitor 처럼 웹 화면을 앱에 담으면 이벤트는 웹 SDK 가 그대로 보내고, 광고·분석 도구는 브라우저 픽셀 대신 앱의 Google 애널리틱스(Firebase)·Meta 앱 이벤트로 보내야 앱 설치 광고를 잴 수 있어요. 앱 측정 모듈을 받아(광고·분석 도구 붙이기) appShell 로 넘기면 돼요.

import { registerPlugin } from "@capacitor/core";
import { capacitorTools } from "allob-measurement/capacitor";
import { build } from "./allob/index.ts";

const tools = capacitorTools(registerPlugin, { metaClientToken: import.meta.env.VITE_META_CLIENT_TOKEN });
const analytics = build({ appShell: { tools, excluded: await tools.isTestLabDevice() } });

• 시작할 때 나라를 한 번 물어요. 동의를 먼저 받아야 하는 나라(스키마 tracking.consent)에서는 appShell.prompt: true 로 두고 동의를 받은 뒤 allowTools() 를 불러요. 동의 창이 없으면 그 나라에서는 도구를 켜지 않아요.
• 이벤트마다 스키마의 appTools 줄대로 도구로 보내요. 앱 이벤트가 아니어도(웹 쪽 이벤트) 줄을 적으면 돼요.
• 스토어 결제는 analytics.storePurchase({ productId, transactionId, price, currency }) 로 도구에 넘겨요.
• 앱 껍데기에서는 브라우저 픽셀·GA 스크립트를 불러오지 않아요.
• excluded: true 면 이번 실행은 아무 데도 보내지 않아요. 구글 플레이 출시 전 보고서 같은 자동 테스트 기기를 빼는 데 써요.

#전송 방식

이벤트는 최대 20개(16KB)씩 모아서 보내고, 페이지를 떠날 때는 sendBeacon 으로 남은 것을 보내요. 전송에 실패하면 최대 세 번까지 보내요. 스키마에서 send: "now" 로 정한 이벤트는 모으지 않고 바로 보내요. 같은 이벤트를 다시 보내도 이벤트 ID 가 같아서 한 번으로 세요.

이벤트는 내 사이트를 거치지 않고 allob 으로 바로 가요. 국가·봇·요청 한도(IP·기기마다)는 allob 이 요청을 받을 때 직접 확인해요(자동으로 걸러지는 것). 따로 넣을 코드는 없어요.

SDK 에는 제품의 수집 키가 들어 있어요. 수집 키는 공개 값이라 코드에 들어가도 괜찮아요. 키를 바꾸려면 allob ingest key --rotate --yes 를 실행해요. 이전 키는 1분 안에 멈추기 때문에, allob sdk pull 로 SDK 를 다시 받아 배포하기 전까지는 이벤트가 쌓이지 않아요.

배포하기 전에 allob sdk pull --check 를 실행하면 받은 SDK 가 allob.schema.json 과 같은 버전인지, 손으로 고친 파일이 없는지 확인해요. 어긋나면 끝 코드 1 로 멈춰서 배포 스크립트나 CI 에 넣기 좋아요. 로그인 없이 돌아요.

마크다운으로 보기 · llms.txt · 개인정보 처리방침 · 이용약관