# เซสชันโทเค็น

เซสชันโทเค็นเป็น**โทเค็นแบบใช้แล้วทิ้ง**ที่อนุญาตให้เล่นเกมหรือสตรีมได้ 1 ครั้ง แต่ละโทเค็นรับประกันว่าจะถูกใช้เพียงครั้งเดียว ป้องกันการใช้งานที่ไม่ถูกต้อง

:::caution[กรุณาเปิดใช้ "Require API Session Token"]
ในการเปิดใช้เซสชันโทเค็น คุณต้องเปิดการตั้งค่า**"Require API Session Token"**ในแท็บ**การตั้งค่า**ของแต่ละเกมหรือสตรีม หากปิดการตั้งค่านี้ เกมจะเล่นได้โดยไม่มีข้อจำกัดของโทเค็น
:::
## วงจรชีวิตของโทเค็น

เซสชันโทเค็นผ่านสถานะต่อไปนี้:

```
active  →  consumed   (ผู้ใช้เล่นเกม)
        →  expired    (โทเค็นหมดอายุ)
        →  revoked    (ถูกยกเลิกด้วยตนเอง)
```

## ขั้นตอนที่ 1: สร้างเซสชัน

เรียก endpoint สร้างเซสชันจากเซิร์ฟเวอร์ด้วย API Key:

```bash
curl -X POST https://app.dailyplay.ai/api/org-api-keys?action=create-session \
  -H "Content-Type: application/json" \
  -H "x-api-key: dpk_YOUR_API_KEY" \
  -d '{
    "game_id": 42,
    "external_ref": "user-12345",
    "metadata": { "campaign": "summer-promo" },
    "expires_in_minutes": 60
  }'
```

### พารามิเตอร์คำขอ

| พารามิเตอร์           | ประเภท | จำเป็น                                | คำอธิบาย                                               |
| --------------------- | ------ | ------------------------------------- | ------------------------------------------------------ |
| `game_id`             | number | `game_id` หรือ `stream_id` อย่างใดอย่างหนึ่ง | เกมที่อนุญาตให้เข้าถึง                                  |
| `stream_id`           | number | `game_id` หรือ `stream_id` อย่างใดอย่างหนึ่ง | สตรีมที่อนุญาตให้เข้าถึง                                |
| `external_ref`        | string | ไม่                                   | ID อ้างอิงสำหรับติดตาม (เช่น User ID, Order ID)         |
| `metadata`            | object | ไม่                                   | ข้อมูล JSON ตามต้องการสำหรับติดตาม                      |
| `expires_in_minutes`  | number | ไม่                                   | ระยะเวลาหมดอายุเป็นนาที (ค่าเริ่มต้น: 1440 = 24 ชั่วโมง) |

### การตอบกลับ

```json
{
  "success": true,
  "data": {
    "token": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
    "stream_id": null,
    "game_id": 42,
    "expires_at": "2026-02-17T12:00:00.000Z",
    "external_ref": "user-12345"
  }
}
```

## ขั้นตอนที่ 2: รีไดเรกต์ผู้ใช้

สร้าง URL พร้อมเซสชันโทเค็นแล้วรีไดเรกต์ผู้ใช้:

```
https://app.dailyplay.ai/embed/42?session_token=a1b2c3d4-e5f6-7890-abcd-ef1234567890
```

สำหรับสตรีม:

```
https://app.dailyplay.ai/stream/<org-slug>/<stream_id>?session_token=a1b2c3d4-e5f6-7890-abcd-ef1234567890
```

## ขั้นตอนที่ 3: ตรวจสอบโทเค็น

ตรวจสอบว่าโทเค็นยังใช้งานได้และไม่หมดอายุก่อนอนุญาตให้เล่น:

```bash
curl https://app.dailyplay.ai/api/org-api-keys?action=validate-session&token=a1b2c3d4-e5f6-7890-abcd-ef1234567890
```

### การตอบกลับ

```json
{
  "success": true,
  "data": {
    "valid": true,
    "status": "active",
    "stream_id": null,
    "game_id": 42,
    "expires_at": "2026-02-17T12:00:00.000Z",
    "external_ref": "user-12345",
    "metadata": { "campaign": "summer-promo" }
  }
}
```

## ขั้นตอนที่ 4: ใช้โทเค็น

เมื่อผู้ใช้เริ่มเล่น โทเค็นจะถูกใช้และไม่สามารถนำกลับมาใช้ซ้ำ:

```bash
curl -X POST https://app.dailyplay.ai/api/org-api-keys?action=consume-session \
  -H "Content-Type: application/json" \
  -d '{
    "token": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
    "player_uuid": "player-uuid-here"
  }'
```

### การตอบกลับสำเร็จ

```json
{
  "success": true,
  "data": {
    "session_id": 1,
    "org_id": 5,
    "stream_id": null,
    "game_id": 42,
    "external_ref": "user-12345",
    "metadata": { "campaign": "summer-promo" }
  }
}
```

### ใช้แล้วหรือหมดอายุ

หากโทเค็นถูกใช้แล้วหรือหมดอายุ API จะตอบกลับ `410 Gone`:

```json
{
  "success": false,
  "error": "Session is invalid, already consumed, or expired"
}
```

## คุณสมบัติของโทเค็น

| คุณสมบัติ              | คำอธิบาย                                                  |
| ---------------------- | --------------------------------------------------------- |
| `token`                | UUID v4 — ส่งไปกับ URL เกม                                |
| `stream_id` / `game_id` | ทรัพยากรเป้าหมาย (ต้องมีอย่างน้อย 1 อย่าง)              |