> ## Documentation Index
> Fetch the complete documentation index at: https://docs.didit.me/llms.txt
> Use this file to discover all available pages before exploring further.

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

> Didit SDK로 기기에서 범위 제한 자격 증명을 사용해 로그인, 게임 플레이, 세션 활동 이벤트를 수집하세요. 주체 바인딩과 네트워크 컨텍스트는 서버에서 적용됩니다.

사기에 중요한 대부분의 [이벤트](https://docs.didit.me/ko/transaction-monitoring/events.md)는 기기에서 발생합니다. 로그인, 세션, 게임 라운드, 사람과 스크립트를 구분하는 타이밍 텔레메트리가 여기에 해당합니다. 기기 레인은 브라우저에 API 키를 넣지 않고 이 이벤트들을 전송합니다.

백엔드가 단일 사용자로 범위가 제한된 단기 자격 증명을 발급하고, 앱은 이 자격 증명으로 이벤트를 전송합니다.

## 흐름

**1. 모니터링 자격 증명 발급**

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

**2. 기기에서 제출**

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

**3. 평소와 같이 규칙 실행**

이벤트는 서버에서 제출된 이벤트와 정확히 같은 [규칙](https://docs.didit.me/ko/transaction-monitoring/event-rules.md)으로 보강, 집계, 평가됩니다.

## 자격 증명 발급

> [!NOTE]
>
> 자격 증명을 발급하려면 애플리케이션에서 [이벤트 수집](https://docs.didit.me/ko/transaction-monitoring/events.md)이 켜져 있어야 합니다. 꺼져 있으면 이 엔드포인트는 쓸 수 없는 자격 증명을 발급하는 대신 `403`과 `{"code": "event_monitoring_disabled"}`를 반환합니다.

```bash theme={null}
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"
  }'
```

```json theme={null}
{
  "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`이 정확히 일치해야 합니다. |

## 제출

```bash theme={null}
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은 요청에서 도출되며, 규칙 평가에서는 이렇게 서버에서 도출된 값이 클라이언트 힌트보다 우선합니다. 규칙 근거에는 그 차이가 [필드 출처](https://docs.didit.me/ko/transaction-monitoring/event-rules.md#증거)로 기록됩니다.
* **카테고리 범위.** `session` 범위의 자격 증명은 `payment` 이벤트를 제출할 수 없으며, 이 경우 `400`으로 거부됩니다.
* **사용 한도.** 배치는 이벤트마다 1회를 소비하므로, 500개 이벤트 배치가 10회 사용 자격 증명을 1회 사용으로 우회할 수 없습니다.
* **Origin 바인딩.** `bind_to_origin`이 설정되어 있으면, `Origin`이 일치하지 않는 요청은 거부되며, `Origin`이 전혀 없는 요청도 거부됩니다.

## 배치 처리

```bash theme={null}
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개 이벤트를 보낼 수 있으며, 항목별 결과는 [서버 배치 엔드포인트](https://docs.didit.me/ko/transaction-monitoring/events.md#배치)와 같습니다. 권장 기본 플러시 조건은 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`은 이미 거래 자격 증명 경로를 사용하는 앱이 점진적으로 전환할 수 있도록 임시 별칭으로 허용됩니다.

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

## 레인 선택

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

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

## 다음 단계

> [card] [이벤트 수집](https://docs.didit.me/ko/transaction-monitoring/events.md)
>
> 이벤트 엔벌로프, 카테고리, 보존 기간, 멱등성을 설명합니다.

> [card] [이벤트 규칙](https://docs.didit.me/ko/transaction-monitoring/event-rules.md)
>
> 빈도, 비율, 순서, 상관관계 규칙을 설명합니다.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.