> ## 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-Event-Übermittlung: clientseitige Erfassung

> Didit erfasst Logins, Gameplay und Sitzungsaktivität vom Gerät per eingeschränktem Token; Subjektbindung und Netzwerkkontext serverseitig erzwungen.

Die meisten [Ereignisse](https://docs.didit.me/de/transaction-monitoring/events.md), die für Betrug relevant sind, entstehen auf dem Gerät: die Anmeldung, die Sitzung, die Gameplay-Runde und die Timing-Telemetrie, die eine Person von einem Skript unterscheidet. Die Geräte-Lane sendet diese Ereignisse, ohne einen API-Schlüssel im Browser zu hinterlegen.

Ihr Backend stellt ein kurzlebiges Credential aus, das auf einen Benutzer beschränkt ist. Die App sendet Ereignisse damit.

## Ablauf

**1. Monitoring-Credential ausstellen**

Ihr Backend ruft `POST /v3/events/sdk-token/` mit Ihrem API-Schlüssel und dem `vendor_data` des Benutzers auf.

**2. Vom Gerät aus senden**

Die App sendet an `POST /v1/events/` (oder `POST /v1/events/batch/`) mit dem Header `X-Monitoring-Token`.

**3. Regeln laufen wie gewohnt**

Das Ereignis wird angereichert, aggregiert und von genau denselben [Regeln](https://docs.didit.me/de/transaction-monitoring/event-rules.md) ausgewertet wie ein serverseitig gesendetes Ereignis.

## Credential ausstellen

> [!NOTE]
>
> Zum Ausstellen eines Credentials muss die [Ereignisaufnahme](https://docs.didit.me/de/transaction-monitoring/events.md) für die Anwendung aktiviert sein. Ist sie deaktiviert, antwortet dieser Endpoint mit `403` und `{"code": "event_monitoring_disabled"}`, statt ein Credential auszustellen, das nie schreiben könnte.

```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"
}
```

| Feld | Standard | Hinweise |
| - | - | - |
| `vendor_data` | erforderlich | Das Subjekt, zu dem alle mit diesem Credential gesendeten Ereignisse gehören. |
| `entity_type` | `individual` | `individual` oder `company`. |
| `allowed_event_categories` | alle | Begrenzt, was ein offengelegtes Credential schreiben könnte. |
| `ttl_seconds` | 900 | 60 - 86400. |
| `max_uses` | 1000 | Eine Nutzung pro **Ereignis**, nicht pro Anfrage. |
| `bind_to_origin` | keine | Ist der Wert gesetzt, muss der Browser-`Origin` exakt übereinstimmen. |

## Senden

```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" }
  }'
```

Beachten Sie, was die Payload **nicht** enthält: keinen API-Schlüssel und kein Subjekt. Beides wird serverseitig erzwungen.

## Was der Server durchsetzt

* **Subjekt-Bindung.** Das Credential ist beim Ausstellen auf ein `vendor_data` beschränkt. Ein `subject`-Block im Request-Body wird überschrieben, sodass ein manipulierter Client nicht in die Zeitleiste eines anderen Benutzers schreiben kann.
* **Netzwerkkontext.** Adresse, User-Agent, accept-language und Origin werden aus der Anfrage abgeleitet. Diese serverseitig ermittelten Werte haben bei der Regelauswertung Vorrang vor jedem Client-Hinweis. Der Nachweis für die Regel hält den Unterschied als [Feldquelle](https://docs.didit.me/de/transaction-monitoring/event-rules.md#belege) fest.
* **Kategoriebeschränkung.** Ein auf `session` beschränktes Credential kann kein `payment`-Ereignis senden. Es wird mit `400` abgelehnt.
* **Nutzungskontingent.** Ein Batch verbraucht eine Nutzung pro Ereignis. Ein Batch mit 500 Ereignissen kann also ein Credential mit 10 Nutzungen nicht als eine einzige Nutzung umgehen.
* **Origin-Bindung.** Ist `bind_to_origin` gesetzt, wird eine Anfrage abgelehnt, deren `Origin` nicht übereinstimmt. Das gilt auch für eine Anfrage ganz ohne `Origin`.

## Batching

```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": [ { "…": "…" }, { "…": "…" } ] }'
```

Bis zu 500 Ereignisse pro Versand, mit denselben Ergebnissen je Element wie beim [Server-Batch-Endpoint](https://docs.didit.me/de/transaction-monitoring/events.md#batches). Ein guter Standardwert für den Versand: 25 Ereignisse, 5 Sekunden oder das Wechseln der Seite bzw. der App in den Hintergrund.

### Was bei Rückstau verworfen wird

Wenn Sie Ereignisse verwerfen müssen, verwerfen Sie die kostengünstigen. Diese dürfen verworfen werden:

`session.page_view` · `session.sdk_heartbeat` · `session.sdk_loaded` · `session.device_seen` · `session.bot_signal_observed` · `bonus.promotion_viewed` · `affiliate.referral_clicked`

Diese dagegen müssen zuerst gesendet werden:

alle Ereignisse der Kategorien `security`, `payment`, `dispute` und `responsible_gambling` sowie `gameplay.bet_placed`, `gameplay.bet_settled` und `gameplay.p2p_settlement`.

Die Listen-Endpoints liefern dieselbe Einstufung pro Ereignis wie `is_droppable` zurück. Ein Client kann sich also daran orientieren, statt eine fest codierte Kopie zu verwenden.

## Header-Kompatibilität

Der kanonische Header ist `X-Monitoring-Token`. `X-Transaction-Token` wird als vorübergehender Alias akzeptiert, damit eine App, die bereits einen Pfad für Transaktions-Credentials nutzt, schrittweise migrieren kann.

> [!WARNING]
>
> Der Alias ist nur übergangsweise gedacht und wird vor der allgemeinen Verfügbarkeit der Events-API entfernt. Verwenden Sie in neuem Code `X-Monitoring-Token`.

## Die passende Lane wählen

| | Geräte-Lane | Server-Lane |
| - | - | - |
| Endpoint | `POST /v1/events/` | `POST /v3/events/` |
| Auth | `X-Monitoring-Token` | `x-api-key` |
| Subjekt | An das Credential gebunden | Im Payload |
| Ideal für | Anmeldungen, Sitzungen, Gameplay, Telemetrie | Zahlungen, Streitfälle, aus dem Hauptbuch abgeleitete Ereignisse, Nachladungen |

Beide Lanes erzeugen identische Ereignisdatensätze und führen identische Regeln aus. Verwenden Sie die Server-Lane immer dann, wenn kein Endbenutzer anwesend ist.

## Weiter

> [card] [Ereignisaufnahme](https://docs.didit.me/de/transaction-monitoring/events.md)
>
> Das Envelope, Kategorien, Aufbewahrung und Idempotenz.

> [card] [Regeln für Ereignisse](https://docs.didit.me/de/transaction-monitoring/event-rules.md)
>
> Frequenz-, Verhältnis-, Sequenz- und Korrelationsregeln.


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