Bắt đầu nhanh

Hướng dẫn này đưa bạn từ lúc chưa có key đến khi một tập được phát: bạn tạo API key, liệt kê catalog được cấp phép, xin vé playback cho một tập và chuyển vé cho player. Mọi lệnh gọi đều chạy từ server của bạn. Các ví dụ dùng curl và một key giả; hãy thay bằng key của bạn.

Trước khi bắt đầu#

Bạn cần:

• Một tài khoản thành viên có vai trò Admin hoặc Developer trong tổ chức của bạn trên partner.wandura.ai.
• Một tổ chức đã được cấp phép stream ít nhất một phim. Nếu catalog trả về rỗng, hãy hỏi Wandura.
• Để playback: một API key có scope playback do bạn tự tạo trên Developers (chọn Stream films in an app; nếu key bị lộ, bất kỳ ai cũng stream được phim bạn được cấp phép, nên hãy thu hồi ngay), và Player SDK đã được cài đặt trong app. Wandura đăng ký app ID của bạn và cấp license Player SDK; tổ chức của bạn trả tiền license đó. Các bước cài nằm trong hướng dẫn Player SDK ở partner.wandura.ai → Developers → Player SDK, có sau khi onboarding.

Bước 1: Tạo API key#

1. Đăng nhập partner.wandura.ai và mở Developers.
2. Trong Create a key, nhập một label cho biết key sẽ chạy ở đâu, ví dụ cms-prod.
3. Trong What will this key do?, chọn Stream films in an app. Key nhận metadata:read và playback, nên dùng được cho mọi bước trên trang này.
4. Chọn Create key và sao chép key ngay. Key chỉ hiện một lần.

Lưu key trong secrets manager và cấp cho backend dưới dạng biến môi trường:

export WANDURA_API_KEY="wnd_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"

Cảnh báo: Key này stream được các phim bạn được cấp phép. Nếu key bị lộ, bất kỳ ai cũng stream được: hãy thu hồi ngay trên Developers. Xem Xác thực.

Bước 2: Liệt kê catalog#

curl -s https://www.wandura.ai/api/delivery/v1/catalog \
  -H "Authorization: Bearer $WANDURA_API_KEY"

Response có hai mảng. films đã được sắp theo thứ tự hiển thị. episodes liệt kê mọi tập của các phim đó; hãy chọn một tập có "stream_ready": true và ghi lại id của nó.

{
  "films": [
    {
      "id": "3f6c1a52-8d0e-4b7a-9c21-5e4f2a7b9d10",
      "title": "The Heiress Returns",
      "slug": "the-heiress-returns",
      "display_order": 10,
      "planned_episodes": 60,
      "free_until_episode": 5
    }
  ],
  "episodes": [
    {
      "id": "b2a4d6e8-1c3f-4a5b-8d7e-9f0a1b2c3d4e",
      "film_id": "3f6c1a52-8d0e-4b7a-9c21-5e4f2a7b9d10",
      "episode_no": 1,
      "status": "published",
      "stream_ready": true
    }
  ]
}

Ví dụ trên đã được rút gọn. Danh sách trường đầy đủ nằm trong tài liệu tham chiếu catalog.

Bước 3: Xin vé playback#

Trên thiết bị của người xem, lấy device ID và device public key từ Player SDK rồi gửi cả hai về backend. Sau đó backend gọi POST /playback bằng key playback:

curl -s -X POST https://www.wandura.ai/api/delivery/v1/playback \
  -H "Authorization: Bearer $WANDURA_PLAYBACK_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "episode_id": "b2a4d6e8-1c3f-4a5b-8d7e-9f0a1b2c3d4e",
    "union_info": "<device ID from the Player SDK>",
    "drm_kek": "<device public key from the Player SDK>",
    "viewer_ref": "session-7f3a91",
    "intent": "play"
  }'

{
  "vid": "v0d2f8c1a9e4b7",
  "play_auth_token": "eyJhbGciOi...placeholder...",
  "expires_at": "2026-10-01T12:30:00.000Z",
  "protection": "private-encrypted",
  "subtitles": [
    { "lang": "en", "url": "https://cdn.example.com/subtitles/ep1-en.vtt", "format": "webvtt" }
  ]
}

Nếu bạn bỏ union_info và drm_kek, API trả 409 với error_code sdk_required: tập đã mã hoá chỉ phát được qua Player SDK.

Bước 4: Phát tập#

Trả vid, play_auth_token và subtitles về thiết bị. Tại đó, đưa video ID và token cho Player SDK rồi bắt đầu phát. SDK tự tải stream và khoá giải mã.

// Pseudocode — use the calls named in the Player SDK guide on the portal
player.setVideoId(response.vid)
player.setPlayAuthToken(response.play_auth_token)
player.play()

Vé hết hạn vào expires_at. Hãy xin vé mới cho mỗi lần bắt đầu phát thay vì cache vé. Xem Playback.

Cảnh báo: Không bao giờ gửi API key xuống thiết bị, và không bao giờ ghi log play_auth_token.

Bước tiếp theo#

• Xác thực: scope, xoay vòng và thu hồi key.
• Playback: thời hạn vé, retry, phụ đề và trường intent.
• Lỗi: mọi mã lỗi và cách xử lý.