Lịch sử thay đổi
Mọi lần sửa trang này, mới nhất ở trên. Mở từng mục để xem đã đổi gì.
- 02/10/2026 · +82 −56 dòng
Xem thay đổi
# 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. + > **TL;DR** — **Phần A** (khoảng 5 phút, chỉ cần server): tạo key, đọc cấu hình, liệt kê catalog. **Phần B** (cần app của bạn chạy trên điện thoại thật có Player SDK): lấy vé đầu tiên và phát một tập. Không test vé được chỉ bằng `curl`: các giá trị thiết bị của vé chỉ có trên thiết bị. - ## Trước khi bắt đầu + Mọi lệnh bên dưới dùng một biến môi trường là `WANDURA_API_KEY`. Phần B thêm `UNION_INFO` và `DRM_KEK`, sao chép từ app của bạn. - Bạn cần: + ## Trước khi bắt đầu {#before-you-start} - - 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](https://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](before-you-start.md#get-onboarded). + - 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](https://partner.wandura.ai). Chưa có quyền truy cập? Xem [Trước khi bắt đầu](before-you-start.md#get-onboarded). + - Ít nhất một phim đã được cấp phép cho tổ chức của bạn, nếu không catalog sẽ rỗng. + - Chỉ cho Phần B: Player SDK đã được cài trong app, kèm giấy phép cho các app ID của bạn. Xem [Player SDK](player-sdk/index.md). - ## Bước 1: Tạo API key + ## Phần A — những lệnh gọi đầu tiên (chỉ server) {#part-a} - 1. Đăng nhập [partner.wandura.ai](https://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. + ### Bước 1: Tạo key {#step-1} - Lưu key trong secrets manager và cấp cho backend dưới dạng biến môi trường: + **Cần:** vai trò Admin hoặc Developer. + 1. Đăng nhập partner.wandura.ai và mở **Developers** → **Create a key**. + 2. Đặt label, ví dụ `quickstart`, và chọn **Stream films in an app**. Key nhận `metadata:read` và `playback`. + 3. Chọn **Create key** và sao chép key ngay: key chỉ hiện một lần. + ```bash 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](authentication.md). + **Nếu lỗi:** không thấy trang **Developers** nghĩa là vai trò của bạn không phải Admin hay Developer: hãy hỏi Admin của tổ chức. **Tiếp theo:** bước 2. - ## Bước 2: Liệt kê catalog + ### Bước 2: Đọc cấu hình {#step-2} + **Cần:** key từ bước 1 (scope nào cũng được). + ```bash + curl -s https://www.wandura.ai/api/delivery/v1/config \ + -H "Authorization: Bearer $WANDURA_API_KEY" + ``` + + **Kết quả mong đợi:** `200` kèm các scope của key, các giới hạn của bạn và phiên bản API mà key được ghim (đã rút gọn): + + ```json + { + "api": { "status": "beta", "version": "2026-10-02", "pinned_version": "2026-10-02", "latest_version": "2026-10-02" }, + "key": { "scopes": ["metadata:read", "playback"] }, + "rate_limits": { "window_seconds": 60, "doors": { "playback": { "limit": 10800, "unit": "tickets" } } }, + "playback": { "grant_ttl_seconds": 1800, "batch": { "max_episodes": 3, "max_next": 2 } } + } + ``` + + **Nếu lỗi:** `401` = biến môi trường rỗng hoặc key bị gõ sai (`echo ${#WANDURA_API_KEY}` phải in ra 41). `503` = thử lại sau `Retry-After`. **Tiếp theo:** bước 3. + + ### Bước 3: Liệt kê catalog {#step-3} + + **Cần:** một key có `metadata:read`. + + ```bash 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ó. + **Kết quả mong đợi:** `200` kèm `films` (theo thứ tự hiển thị) và `episodes` (đã rút gọn): ```json { "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 - } + { "id": "3f6c1a52-8d0e-4b7a-9c21-5e4f2a7b9d10", "title": "The Heiress Returns", "slug": "the-heiress-returns", "display_order": 10, "free_until_episode": 1 } ], "episodes": [ - { - "id": "b2a4d6e8-1c3f-4a5b-8d7e-9f0a1b2c3d4e", - "film_id": "3f6c1a52-8d0e-4b7a-9c21-5e4f2a7b9d10", - "episode_no": 1, - "status": "published", - "stream_ready": true - } + { "id": "b2a4d6e8-1c3f-4a5b-8d7e-9f0a1b2c3d4e", "film_id": "3f6c1a52-8d0e-4b7a-9c21-5e4f2a7b9d10", "episode_no": 1, "status": "published", "stream_ready": true, "poster_url": null } ] } ``` - 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](reference/catalog.md). + Chọn một tập có `"stream_ready": true` và ghi lại `id` của nó cho Phần B. Catalog lớn? Phân trang bằng `limit`; xem [Đồng bộ catalog](guides/catalog-sync.md). - ## Bước 3: Xin vé playback + **Nếu lỗi:** `200` **rỗng** (`"films": []`) nghĩa là tổ chức của bạn chưa có giấy phép nào đang hiệu lực, không phải key hỏng: hãy hỏi Wandura trong kênh Discord của team bạn. `403` = key thiếu `metadata:read`. **Tiếp theo:** xây [job đồng bộ catalog](guides/catalog-sync.md), hoặc chuyển sang Phần B. - 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`: + ## Phần B — vé đầu tiên trên thiết bị thật {#part-b} + **Cần:** app của bạn chạy trên một iPhone hoặc điện thoại Android thật, Player SDK đã khởi động và đã qua bước kiểm giấy phép, và playback key nằm trên backend của bạn. Simulator và emulator không tạo ra giá trị thiết bị dùng được. + + > **Cảnh báo:** Mọi vé Wandura cấp đều được ghi nhận, và vé có `"intent": "play"` được tính là một lượt xem phim. Hãy làm các bước này với thiết bị thật và một người xem test thật, không dùng giá trị bịa ra. + + ### Bước 4: Đọc giá trị thiết bị trong app {#step-4} + + Trong app, sau khi Player SDK đã khởi động, đọc **device ID** và **device public key** (lệnh gọi chính xác nằm trong hướng dẫn Player SDK trên portal), rồi ghi log chúng một lần trong bản build debug. Trên shell của backend: + ```bash + export UNION_INFO="<device ID logged by your debug build>" + export DRM_KEK="<device public key logged by your debug build>" + ``` + + **Nếu lỗi:** giá trị kiểu `(null)` hoặc chuỗi rỗng nghĩa là SDK chưa khởi động hoặc kiểm giấy phép thất bại. Xem [Player SDK](player-sdk/index.md#common-problems). + + ### Bước 5: Xin vé {#step-5} + + Từ backend, cho tập bạn đã chọn ở bước 3: + + ```bash curl -s -X POST https://www.wandura.ai/api/delivery/v1/playback \ - -H "Authorization: Bearer $WANDURA_PLAYBACK_KEY" \ + -H "Authorization: Bearer $WANDURA_API_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", + "union_info": "'"$UNION_INFO"'", + "drm_kek": "'"$DRM_KEK"'", + "viewer_ref": "qa-viewer-1:device-1", "intent": "play" }' ``` + Nếu `UNION_INFO` và `DRM_KEK` rỗng, Wandura trả `409` `sdk_required` và không cấp gì. + + **Kết quả mong đợi:** `200`: + ```json { "vid": "v0d2f8c1a9e4b7", - "play_auth_token": "eyJhbGciOi...placeholder...", - "expires_at": "2026-10-01T12:30:00.000Z", + "play_auth_token": "placeholder-play-token", + "expires_at": "2026-10-02T12:30:00.000Z", "protection": "private-encrypted", "subtitles": [ ⋯ ``` - 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ã. + **Nếu lỗi:** `400` `invalid_device_info` = một giá trị thiết bị trông như rỗng (`fields` cho biết giá trị nào). `403` `not_entitled` = phim chưa được cấp phép cho tổ chức này. `404` `not_ready` = sai `episode_id`, hoặc tập chưa sẵn sàng. Mọi mã lỗi: [Lỗi](concepts/errors.md#playback-errors). - ```text - // 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() - ``` + ### Bước 6: Phát {#step-6} - 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](concepts/playback.md). + Trả `vid`, `play_auth_token` và `subtitles` về đúng 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 đã mã hoá và khoá của nó. Player HLS thông thường không phát được các tập này: nó tải playlist rồi đứng hình. - > **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`. + **Kết quả mong đợi:** tập bắt đầu phát trong vài giây. **Nếu lỗi:** xem [Player SDK · các vấn đề thường gặp](player-sdk/index.md#common-problems). Vé hết hạn vào `expires_at` (30 phút); xin lại cho cùng tập, trên cùng thiết bị, với cùng `viewer_ref` sẽ nhận lại đúng vé đó nếu vé còn hơn 5 phút. - ## Bước tiếp theo + ## Bước tiếp theo {#next-steps} - - [Xác thực](authentication.md): scope, xoay vòng và thu hồi key. - - [Playback](concepts/playback.md): thời hạn vé, retry, phụ đề và trường `intent`. - - [Lỗi](concepts/errors.md): mọi mã lỗi và cách xử lý. + - [Lộ trình tích hợp](integration-guide.md): toàn bộ lộ trình tới go-live. + - [Luồng playback và paywall](guides/playback-flow.md): endpoint backend mà app của bạn gọi, kèm code. + - [Bảo mật](concepts/security.md): đọc trước khi đưa bất kỳ key nào lên một server dùng chung.
- 01/10/2026 · +3 −3 dòng
Xem thay đổi
⋯ - 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](https://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 Wandura cấp cho bạn, 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](before-you-start.md#get-onboarded). + - Để 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](before-you-start.md#get-onboarded). ## Bước 1: Tạo API key ⋯ 1. Đăng nhập [partner.wandura.ai](https://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. Đảm bảo **Read film metadata** (`metadata:read`) đã được tích. Mục này được chọn sẵn. + 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. ⋯ ``` - Key bạn tự tạo đọc được catalog nhưng không phát được video. Ở bước 3, bạn cần key có scope `playback` mà Wandura đã cấp cho bạn. Xem [Xác thực](authentication.md). + > **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](authentication.md). ## Bước 2: Liệt kê catalog ⋯
- 01/10/2026 · +2 −2 dòng
Xem thay đổi
⋯ - 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](https://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 Wandura cấp cho bạn, và Player SDK đã được cài đặt trong app. Wandura cung cấp giấy phép SDK và đăng ký bundle ID hoặc package name của app bạn trong quá trình onboarding. + - Để playback: một API key có scope `playback` do Wandura cấp cho bạn, 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](before-you-start.md#get-onboarded). ## Bước 1: Tạo API key ⋯ ```text - // Pseudocode — use the calls named in your Player SDK onboarding pack + // Pseudocode — use the calls named in the Player SDK guide on the portal player.setVideoId(response.vid) player.setPlayAuthToken(response.play_auth_token) ⋯
- 01/10/2026 · +1 −1 dòng
Xem thay đổi
⋯ - 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](https://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 đầu mối đối tác Wandura của bạn. + - 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 Wandura cấp cho bạn, và Player SDK đã được cài đặt trong app. Wandura cung cấp giấy phép SDK và đăng ký bundle ID hoặc package name của app bạn trong quá trình onboarding. ⋯
- 29/09/2026 · Tạo trang