SDK 이벤트 제출 - 클라이언트 측 이벤트 수집

사기에 중요한 대부분의 이벤트는 기기에서 발생합니다. 로그인, 세션, 게임 라운드, 사람과 스크립트를 구분하는 타이밍 텔레메트리가 여기에 해당합니다. 기기 레인은 브라우저에 API 키를 넣지 않고 이 이벤트들을 전송합니다. 백엔드가 단일 사용자로 범위가 제한된 단기 자격 증명을 발급하고, 앱은 이 자격 증명으로 이벤트를 전송합니다.

흐름

모니터링 자격 증명 발급

백엔드가 API 키와 사용자의 vendor_data를 사용해 POST /v3/events/sdk-token/를 호출합니다.

기기에서 제출

앱이 X-Monitoring-Token 헤더와 함께 POST /v1/events/(또는 POST /v1/events/batch/)로 전송합니다.

평소와 같이 규칙 실행

이벤트는 서버에서 제출된 이벤트와 정확히 같은 규칙으로 보강, 집계, 평가됩니다.

자격 증명 발급

자격 증명을 발급하려면 애플리케이션에서 이벤트 수집이 켜져 있어야 합니다. 꺼져 있으면 이 엔드포인트는 쓸 수 없는 자격 증명을 발급하는 대신 403과 {"code": "event_monitoring_disabled"}를 반환합니다.

curl -X POST https://verification.didit.me/v3/events/sdk-token/ \
  -H "x-api-key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "vendor_data": "user_391",
    "allowed_event_categories": ["auth", "session", "gameplay"],
    "ttl_seconds": 900,
    "max_uses": 1000,
    "bind_to_origin": "https://operator.example"
  }'

{
  "monitoring_token": "…",
  "expires_at": "2026-08-31T21:00:00Z",
  "allowed_event_categories": ["auth", "session", "gameplay"],
  "max_uses": 1000,
  "bind_to_origin": "https://operator.example"
}

필드	기본값	설명
`vendor_data`	필수	이 자격 증명으로 전송되는 모든 이벤트가 속하는 대상입니다.
`entity_type`	`individual`	`individual` 또는 `company`입니다.
`allowed_event_categories`	전체	유출된 자격 증명이 기록할 수 있는 범위를 좁힙니다.
`ttl_seconds`	900	60 - 86400
`max_uses`	1000	이벤트 하나당 1회 사용하며, 요청 하나당 1회가 아닙니다.
`bind_to_origin`	없음	설정하면 브라우저의 `Origin`이 정확히 일치해야 합니다.

제출

curl -X POST https://verification.didit.me/v1/events/ \
  -H "X-Monitoring-Token: THE_MINTED_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "event_id": "session-abc-login-1",
    "event_category": "auth",
    "action_type": "login",
    "occurred_at": "2026-08-31T20:40:31.123Z",
    "session": { "session_id": "web-session-abc", "sequence": 1 },
    "device_context": { "fingerprint": "didit-fp-v2:a8c1" },
    "payload": { "method": "password" }
  }'

페이로드에 포함되지 않는 항목을 확인하세요. API 키와 대상 정보가 없으며, 두 가지 모두 서버에서 강제로 적용됩니다.

서버가 강제하는 항목

대상 바인딩. 자격 증명은 발급 시점에 하나의 vendor_data에 범위가 지정됩니다. 요청 본문의 subject 블록은 덮어써지므로, 변조된 클라이언트는 다른 사용자의 타임라인에 기록할 수 없습니다.
네트워크 컨텍스트. IP 주소, user agent, accept-language, origin은 요청에서 도출되며, 규칙 평가에서는 이렇게 서버에서 도출된 값이 클라이언트 힌트보다 우선합니다. 규칙 근거에는 그 차이가 필드 출처로 기록됩니다.
카테고리 범위. session 범위의 자격 증명은 payment 이벤트를 제출할 수 없으며, 이 경우 400으로 거부됩니다.
사용 한도. 배치는 이벤트마다 1회를 소비하므로, 500개 이벤트 배치가 10회 사용 자격 증명을 1회 사용으로 우회할 수 없습니다.
Origin 바인딩. bind_to_origin이 설정되어 있으면, Origin이 일치하지 않는 요청은 거부되며, Origin이 전혀 없는 요청도 거부됩니다.

배치 처리

curl -X POST https://verification.didit.me/v1/events/batch/ \
  -H "X-Monitoring-Token: THE_MINTED_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{ "events": [ { "…": "…" }, { "…": "…" } ] }'

플러시 한 번에 최대 500개 이벤트를 보낼 수 있으며, 항목별 결과는 서버 배치 엔드포인트와 같습니다. 권장 기본 플러시 조건은 25개 이벤트, 5초, 또는 페이지/앱이 백그라운드로 전환될 때입니다.

백프레셔 시 버릴 이벤트

이벤트를 버려야 한다면 중요도가 낮은 이벤트부터 버리세요. 다음 이벤트는 버려도 안전합니다: session.page_view · session.sdk_heartbeat · session.sdk_loaded · session.device_seen · session.bot_signal_observed · bonus.promotion_viewed · affiliate.referral_clicked 다음 이벤트는 버리면 안 되며, 가장 먼저 전송하세요: 모든 security, payment, dispute, responsible_gambling 이벤트와 gameplay.bet_placed, gameplay.bet_settled, gameplay.p2p_settlement입니다. 목록 엔드포인트는 이벤트마다 같은 분류를 is_droppable로 반환하므로, 클라이언트는 하드코딩된 사본 대신 이 값을 기준으로 동작할 수 있습니다.

헤더 호환성

표준 헤더는 X-Monitoring-Token입니다. X-Transaction-Token은 이미 거래 자격 증명 경로를 사용하는 앱이 점진적으로 전환할 수 있도록 임시 별칭으로 허용됩니다.

이 별칭은 임시이며, 이벤트 API가 정식 출시되기 전에 제거됩니다. 새 코드에서는 X-Monitoring-Token을 전송하세요.

레인 선택

	기기 레인	서버 레인
엔드포인트	`POST /v1/events/`	`POST /v3/events/`
인증	`X-Monitoring-Token`	`x-api-key`
대상	자격 증명에 바인딩됨	페이로드 안에 포함
적합한 용도	로그인, 세션, 게임, 텔레메트리	결제, 분쟁, 원장 기반 이벤트, 백필

두 레인 모두 동일한 이벤트 레코드를 생성하고 동일한 규칙을 실행합니다. 최종 사용자가 없는 경우에는 항상 서버 레인을 사용하세요.

다음 단계

이벤트 수집

이벤트 엔벌로프, 카테고리, 보존 기간, 멱등성을 설명합니다.

이벤트 규칙

빈도, 비율, 순서, 상관관계 규칙을 설명합니다.

시작하기

기능

레퍼런스

콘솔

SDK 이벤트 제출 - 클라이언트 측 이벤트 수집

흐름

자격 증명 발급

제출

서버가 강제하는 항목

배치 처리

백프레셔 시 버릴 이벤트

헤더 호환성

레인 선택

다음 단계

이벤트 수집

이벤트 규칙

​흐름

​자격 증명 발급

​제출

​서버가 강제하는 항목

​배치 처리

​백프레셔 시 버릴 이벤트

​헤더 호환성

​레인 선택

​다음 단계

이벤트 수집

이벤트 규칙

흐름

자격 증명 발급

제출

서버가 강제하는 항목

배치 처리

백프레셔 시 버릴 이벤트

헤더 호환성

레인 선택

다음 단계