스키마 레퍼런스

이벤트 스키마(allob.schema.json)에 쓸 수 있는 모든 필드예요. 스키마는 보통 에이전트가 작성하니, 이 페이지는 에이전트가 참고하거나 사람이 결과를 확인할 때 써요.

#수정 순서

allob schema pull                      # 현재 버전을 allob.schema.json 으로 받기
# allob.schema.json 수정
allob schema push --dry-run            # 검사만
allob schema push --note "add checkout_start"
allob sdk pull                         # 새 버전으로 SDK 다시 받기
allob sdk pull --check                 # 배포 전에 — SDK 가 스키마와 같은 버전인지(어긋나면 끝 코드 1)

• 올릴 때마다 버전이 하나씩 올라가요. 이전 버전은 allob schema history 로 봐요.
• 받은 버전을 기준으로만 올릴 수 있어요. 그 사이 다른 사람이나 에이전트가 먼저 올렸다면 conflict 에러가 나요. 다시 allob schema pull 해서 합친 뒤 올려요.
• 지금 버전이 받는 이벤트나 저장하는 속성을 지우면 올리지 않고 breaking_change 에러와 지워지는 목록을 보여 줘요. 이름을 바꾸거나, 이벤트를 앱과 서버 사이로 옮기거나, surface 를 바꾸는 것도 지우는 것으로 봐요. 이미 설치된 앱은 예전 방식으로 계속 보내는데, allob 은 그걸 버리기 때문이에요. 정말 바꾸려면 allob schema push --allow-breaking 으로 올려요. 속성의 column 만 바꾸면 올리되 경고를 보여 줘요(그 속성의 예전 데이터와 보드에서 이어지지 않아요).
• 올린 스키마는 1분 안에 이벤트 수집에 반영돼요.
• allob sdk pull --check 는 아무것도 쓰지 않고 로그인 없이 돌아요. 받은 SDK 의 버전이 allob.schema.json 과 다르거나, allob.schema.json 을 고치고 아직 올리지 않았거나, SDK 폴더의 파일을 손으로 고쳤거나 지웠으면 이유를 한 줄씩 보여 주고 끝 코드 1 로 멈춰요. 배포 스크립트나 CI 에 넣어요.
  • 줄 끝만 바뀐 것(윈도의 CRLF)은 고친 것으로 보지 않아요. 코드 정리 도구(Prettier 같은 포매터)가 SDK 폴더를 고치면 고친 것으로 보니, SDK 폴더는 포매터 대상에서 빼 두세요.
  • 스키마가 아직 만들 수 없는 대상만 있는 폴더(예: apps.measurement 가 없는데 native 폴더를 적어 둔 것)는 실패로 치지 않아요. allob sdk pull 도 그 대상은 건너뛰기 때문이에요.

#예시

일기 앱에서 "일기 쓰기 → 결제 화면 → 결제 시작 → 결제"를 측정하는 스키마예요.

{
  "schemaVersion": 1,
  "tracking": {
    "landEvent": "ad_land",
    "allowedHosts": ["diary.example.com"],
    "ga4": { "measurementId": "G-XXXXXXXXXX" }
  },
  "enums": { "plans": ["monthly", "yearly"] },
  "events": {
    "entry_write": {
      "label": "일기 쓰기",
      "props": { "mood": { "enum": ["good", "soso", "bad"] } },
      "order": ["mood"]
    },
    "paywall_view": {
      "label": "결제 화면",
      "props": { "from": { "enum": ["limit", "settings"] } },
      "order": ["from"]
    },
    "checkout_start": {
      "label": "결제 시작",
      "pixel": "InitiateCheckout",
      "ga": "begin_checkout",
      "send": "now",
      "props": { "plan": { "enum": "$plans" }, "price": { "column": "double1" } },
      "order": ["plan"]
    },
    "purchase": {
      "label": "결제(서버)",
      "source": "server",
      "props": { "plan": { "enum": "$plans" }, "value": { "column": "double1" } },
      "order": ["plan"]
    }
  },
  "funnels": {
    "main": { "label": "쓰기 → 결제", "steps": ["entry_write", "paywall_view", "checkout_start", "purchase"] }
  }
}

이 스키마로 SDK 를 받으면 track.entryWrite({ mood: "good" }), track.checkoutStart({ plan: "yearly", price: 39 }) 같은 함수가 생겨요. 목록에 없는 값을 넣으면 타입 검사에서 에러가 나요.

#최상위 필드

dimensions·experiments 는 저장하고 검사하지만, 지표 탭에는 아직 퍼널·방문 기기·리텐션·유입 경로·이벤트만 나와요.

#제품 안 A/B

experiments 에 실험을 적고 SDK 를 다시 받으면, 실험마다 그룹을 돌려주는 함수가 생겨요.

const analytics = build();
const copy = analytics.experiment.pricingCopy(); // "control" | "short"

• 그룹은 기기 id 로 정해져서 같은 기기는 늘 같은 그룹이에요. 서버에 묻지 않아요. 웹·앱·서버(server.ts 의 assignArm(실험, sid))가 같은 기기 id 면 같은 그룹을 줘요.
• 로그인한 사용자는 setUserId(사용자 id) 를 부르면 기기 대신 사용자 id 로 그룹을 정해요. 그래서 같은 사람은 웹·앱·다른 기기에서도 같은 그룹이에요. 사용자 id 는 이벤트에 싣지 않고 광고·분석 도구로도 보내지 않아요. 피드백을 보낼 때만 보낸 사람으로 같이 가요. 로그인을 안 뒤, 실험 함수를 부르기 전에 불러 주세요(이 페이지·이번 실행에서 이미 정한 실험의 그룹은 바뀌지 않아요). 로그아웃하면 setUserId(null) 이에요. 서버는 assignArm(실험, sid, 사용자 id) 로 같은 그룹을 받아요.
• 처음 부를 때 한 번 노출 이벤트 experiment_view(실험·그룹)를 보내요. allob 에만 보내고 광고·분석 도구로는 보내지 않아요. 앱은 start() 뒤에 불러 주세요.
• 그룹의 label 은 지표 화면에 보이는 이름이에요(없으면 id). weight 는 나누는 비율이에요(없으면 1). startedAt·endedAt 은 실험을 시작하고 끝낸 날이에요. 지표 탭의 변경 타임라인에 그날 점으로 보이고, 결과도 이 기간으로 잘라 봐요.
• 계측이 꺼진 기기(추적 거부·동의 전)도 그룹은 받지만 노출은 보내지 않아요.
• setUserId 없이 로그인 등으로 기기 id 를 바꾸면(adoptSid) 그 뒤로 그룹이 바뀔 수 있어요. 지표에서는 그런 기기를 처음 그룹으로만 세고, 몇 대인지 알려 줘요.
• 이벤트 속성에 그룹을 싣던 방식(dimension)도 그대로 쓸 수 있어요.
• 결과는 지표 탭의 퍼널 나눠 보기에서 "실험: 이름"을 고르거나 allob metrics funnel --by exp:<실험> 으로 봐요(지표 — 제품 안 A/B 결과).

#이벤트 필드

#속성 필드

값 목록 속성은 order 순서대로 / 로 이어져 하나로 저장되고, 32자를 넘으면 잘려요. 짧은 값을 쓰세요.

#tracking 필드

#apps 필드

apps.measurement 는 앱 측정 모듈(allob sdk pull 의 native 대상 — 앱에 측정 넣기)이 쓰는 값이에요. 비밀 값은 적지 않아요.

여기서 켠 업체(Google 애널리틱스·Meta·AdMob·미디에이션 네트워크)는 법 문서 사실에 바로 들어가요.

#표준 이벤트

스키마에 적지 않아도 항상 쓸 수 있는 이벤트예요. 웹 SDK 에 같은 이름의 함수가 있어요.

#버전과 호환성

• 이벤트나 속성을 추가하는 건 언제든 괜찮아요. 이미 배포된 SDK 는 새 이벤트를 보내지 않을 뿐이에요.
• 이벤트 이름을 바꾸거나 값의 뜻을 바꾸면 이전 숫자와 이어지지 않아요. 새 이름으로 추가하고, 이전 이벤트에는 endedAt 을 적어 두세요.
• schemaVersion 이 지금 CLI 보다 새로우면 allob update 를 하라고 알려 줘요.

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