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 · +35 −298 dòng
Xem thay đổi
- # Tích hợp app của bạn - - > **TL;DR** — Server của bạn đồng bộ catalog Wandura 15–60 phút một lần vào database của bạn. Khi người xem bấm phát, app kiểm paywall của chính bạn, server xin Wandura vé cho đúng tập đó (và tối đa 2 tập kế để phát liền), rồi Player SDK được cấp phép phát. Bạn không bao giờ cầm key kho video của Wandura: mỗi vé đều được kiểm theo giấy phép của bạn và được Wandura ghi nhận. Go-live = [checklist ở giai đoạn 6](#go-live-checklist). Mô hình khác? Xem [Chọn mô hình tích hợp](integration-models.md). Checklist và giá license: [Trước khi bắt đầu](before-you-start.md). - - Hướng dẫn này đưa đội của bạn từ lúc ký thoả thuận đến khi app chạy thật và phát được phim Wandura. Các bước đi theo đúng thứ tự của một lần tích hợp thật: những gì Wandura dựng sẵn cho bạn, key, job đồng bộ catalog ở backend, luồng playback, feed creative quảng cáo (tuỳ chọn), kế hoạch test và checklist go-live. Mỗi giai đoạn trỏ sang trang tham chiếu để xem chi tiết. + # Lộ trình tích hợp - Mô hình rất đơn giản. **App của bạn quyết định người xem có được xem một tập hay không** (tập miễn phí, xu, gói thuê bao, VIP). **Wandura quyết định app của bạn có được phát phim đó hay không** (giấy phép của bạn), ký một vé ngắn hạn và ghi nhận lượt phát. App của bạn không bao giờ cầm key của kho video Wandura: mỗi lần phát, server của bạn xin Wandura một vé. + > **TL;DR** — Bảy giai đoạn, từ lúc ký thoả thuận đến khi app chạy thật. Mỗi giai đoạn trỏ tới trang làm phần việc đó và cho biết khi nào là xong. Cách chia trách nhiệm và các thành phần nằm ở [Kiến trúc](architecture.md). ```mermaid flowchart LR - p0["0 · Setup by Wandura"] --> p1["1 · Keys"] - p1 --> p2["2 · Catalog sync job"] - p2 --> p3["3 · Playback flow"] - p3 --> p4["4 · Creatives feed (optional)"] - p4 --> p5["5 · Test plan"] + p0["0 · Onboarding"] --> p1["1 · Keys"] + p1 --> p2["2 · Catalog sync"] + p2 --> p3["3 · Playback + paywall"] + p3 --> p4["4 · Player SDK in the app"] + p4 --> p5["5 · Test"] p5 --> p6["6 · Go-live"] ``` - ## Ai làm gì {#responsibilities} - - | Mảng | Wandura | Đội của bạn | - |---|---|---| - | Phim | Sản xuất, mã hoá và bảo vệ mọi phim, mọi tập. Cập nhật tên, tóm tắt, poster, thể loại, thứ tự hiển thị và phụ đề. | Hiển thị trong app đúng thứ tự và đúng nội dung chữ nhận được. | - | Bản quyền | Cấp cho tổ chức của bạn giấy phép streaming theo từng phim, có khung thời gian (ngày bắt đầu, ngày kết thúc, cả hai hoặc không có ngày nào), và kiểm tra ở mọi request xin vé. | Tuân thủ các giới hạn khác trong hợp đồng, ví dụ các quốc gia mà app được chiếu phim. | - | Người xem và tiền | Không có gì. API không có định danh theo từng người xem. | Tài khoản, đăng nhập, paywall, tập miễn phí, xu, gói thuê bao, VIP, hoàn tiền và hỗ trợ người xem. | - | Key | Cấp key phát được video. Cho developer của bạn tự tạo key chỉ đọc. | Giữ mọi key ở server, xoay vòng và thu hồi key, không bao giờ đưa key vào app. | - | Player | Đă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 đó. | Tích hợp Player SDK vào app và làm theo hướng dẫn Player SDK trên cổng. | - | Playback | Ký vé cho một tập trên một thiết bị, và ghi nhận lượt phát. | Chỉ xin vé cho tập người xem được phép xem, rồi chuyển vé cho player. | - | Số liệu | Đếm lượt phát theo từng phim từ các request xin vé của bạn. | Đánh dấu request prefetch là prefetch, để không bị đếm thành lượt phát. | - - ## Giai đoạn 0: Wandura dựng sẵn cho bạn những gì {#phase-0} - - Trước khi developer của bạn viết dòng code nào, Wandura sẽ dựng sẵn các mục dưới đây. Hãy hỏi đúng tên từng mục trong kênh Discord Wandura của team bạn; thứ tự các bước nằm ở [Onboarding](before-you-start.md#get-onboarded). - - | Mục | Là gì | Bạn gửi Wandura | - |---|---|---| - | Tổ chức | Không gian làm việc của đội bạn trên [partner.wandura.ai](https://partner.wandura.ai). Mọi key và giấy phép đều thuộc về nó. | Tên tổ chức và email của người sẽ làm **Admin**. | - | Quyền developer | Developer backend của bạn nhận vai trò **Developer**. Vai trò này chỉ mở trang **Developers**, nơi quản lý key. Admin của tổ chức cũng quản lý được key. | Email của các developer. | - | Giấy phép phim | Một giấy phép streaming cho mỗi phim bạn được chiếu. Khung thời gian có thể có ngày bắt đầu, ngày kết thúc, cả hai hoặc không có ngày nào. | Danh sách phim và ngày trong thoả thuận. | - | Key playback | Một API key có scope `playback`. Developer của bạn tự tạo trên trang **Developers**, mỗi môi trường một key. 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. | Không cần gì: bạn tự tạo. | - | Giấy phép Player SDK | 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 đó. Kèm theo là quyền vào hướng dẫn Player SDK ở partner.wandura.ai → **Developers** → **Player SDK**. | Bundle ID iOS và package name Android mà app sẽ phát hành, không dùng ID tạm. | - - Cách các vai trò hoạt động trên cổng được giải thích ở [Vai trò](../partners/roles.md). - - Ngày của giấy phép tính theo nguyên ngày UTC, tính cả ngày đầu lẫn ngày cuối. Giấy phép không có ngày bắt đầu thì có hiệu lực ngay khi được cấp; không có ngày kết thúc thì chạy đến khi Wandura kết thúc nó. Wandura cũng có thể tắt một giấy phép trước ngày kết thúc. Bạn không cần tự theo dõi ngày: catalog chỉ liệt kê những phim có giấy phép đang hiệu lực hôm nay. - - **Xong khi:** developer của bạn đăng nhập được partner.wandura.ai và mở được **Developers**, bạn đã nhận giấy phép Player SDK, và Wandura đã xác nhận danh sách phim được cấp phép. Developer của bạn tự tạo key playback ở [Giai đoạn 1](#phase-1). - - ## Giai đoạn 1: Key và môi trường {#phase-1} - - Mọi lệnh gọi đều tới một base URL duy nhất, `https://www.wandura.ai`, và chỉ từ server của bạn. Các endpoint không gửi header CORS, và key nằm trong app thì có thể bị trích ra. Cách gửi key xem ở [Xác thực](authentication.md). - - Dùng một key cho mỗi hệ thống và mỗi môi trường, chỉ với các scope hệ thống đó cần: - - | Hệ thống trong backend | Scope | Ai tạo key | - |---|---|---| - | Job đồng bộ catalog | `metadata:read` | Developer của bạn, trên trang **Developers** | - | Dịch vụ playback (server xin vé) | `playback` (kèm `metadata:read`: chọn **Stream films in an app**) | Developer của bạn, trên trang **Developers** | - | Job đồng bộ cho marketing (chỉ khi dùng [Giai đoạn 4](#phase-4)) | `creatives:export` | Developer của bạn, trên trang **Developers** | - - Những luật giúp bạn tránh sự cố về sau: - - - Lưu key trong secrets manager và đọc qua biến môi trường. Không commit key, không đưa key vào app. - - Staging và production dùng key khác nhau, để thu hồi một key mà không ảnh hưởng key kia. - - Nếu key playback bị lộ, bất kỳ ai cũng stream được phim bạn được cấp phép. Bất kỳ **Admin** hoặc **Developer** nào của tổ chức cũng xoay vòng hoặc thu hồi được key trên trang **Developers**: hãy thu hồi ngay nếu nghi key đã bị lộ. Để đổi không gián đoạn, tạo key playback thứ hai, triển khai nó, rồi thu hồi key cũ. Wandura được báo mỗi khi có key playback mới hoặc một key playback được xoay vòng. - - Không bao giờ ghi log nguyên key hay `play_auth_token`. Khi trao đổi với Wandura, chỉ nêu tiền tố key hiện trên trang **Developers**. - - Tạo, xoay vòng và thu hồi key từng bước: [Key cho developer](../partners/developer-keys.md). - - ### Test và production {#test-and-production} - - Không có sandbox. Staging và production gọi cùng một base URL, `https://www.wandura.ai`, và nhận cùng câu trả lời; thứ tách lưu lượng test ra là tổ chức và key. - - - **Tổ chức test.** Wandura quyết định bạn có test trong một tổ chức test riêng hay không. Tổ chức đó chạy như mọi tổ chức khác: thành viên, key và giấy phép phim riêng. - - **Phim để test.** Các phim bạn dùng để test được cấp giấy phép cho tổ chức bạn test. Hỏi chúng trong kênh Discord Wandura của team bạn. - - **Lượt phát test.** Mọi request xin vé đều được ghi nhận, kể cả request test. Đặt tiền tố như `qa-` trong `viewer_ref` cho lưu lượng test, và báo Wandura tổ chức nào là tổ chức test của bạn. - - **Xong khi:** mỗi hệ thống backend có key riêng trong secrets manager, và một lệnh `GET /api/delivery/v1/catalog` từ server staging trả về `200`. - - ## Giai đoạn 2: Job đồng bộ catalog {#phase-2} - - Dựng một job trong backend chép catalog của Wandura vào database của bạn. App đọc phim từ database của bạn: không đọc thẳng từ Wandura, và không đọc từ một danh sách phim thứ hai do ai đó nhập tay. - - ```mermaid - sequenceDiagram - participant Job as Your sync job - participant API as Wandura Delivery API - participant DB as Your database - participant App as Your app - loop Every 15 to 60 minutes - Job->>API: GET /api/delivery/v1/catalog - API-->>Job: films and episodes (the full catalog) - Job->>DB: Upsert rows, mark missing rows unavailable - end - App->>DB: Home, film page, episode list - ``` - - ### Bao lâu chạy một lần {#sync-frequency} - - Chạy job mỗi 15 đến 60 phút, và cho phép người trong đội bấm chạy tay khi Wandura báo có phim mới. Catalog không gửi thông báo thay đổi, nên hỏi định kỳ là cách để thấy thay đổi. Đừng gọi catalog mỗi lần mở app: hãy phục vụ nó từ server của bạn. - - ### Không có cursor, không phân trang {#no-pagination} - - Mỗi response là toàn bộ catalog mà tổ chức của bạn được phát tại thời điểm đó. Không có tham số cursor, trang hay `updated_since`. Hãy coi mỗi response là một bản chụp và so với bản bạn đang giữ. - - ### Lưu những gì {#what-to-store} - - | Bảng | Khoá | Trường cần giữ | Dùng cho | - |---|---|---|---| - | Phim | `films[].id` | `title`, `slug`, `synopsis_short`, `synopsis_full`, `poster_url`, `genres`, `language`, `audience`, `form`, `setting`, `display_order`, `planned_episodes`, `free_until_episode` | Trang chủ, bộ lọc duyệt phim, trang phim, luật paywall của bạn | - | Tập | `episodes[].id`, hoặc `film_id` + `episode_no` | `episode_no`, `title`, `synopsis`, `duration_ms`, `poster_uri`, `status`, `stream_ready` | Danh sách tập, ô "sắp ra mắt", request xin vé | - | Cả hai | — | Lần cuối thấy dòng đó trong response | Phát hiện phim, tập bị rút | - - Mọi trường được mô tả trong [tham chiếu catalog](reference/catalog.md). Những điểm quan trọng với job đồng bộ: - - - **Thứ tự.** Phim về đã xếp theo `display_order`. Giữ nguyên thứ tự đó; Wandura là bên chỉnh. - - **Tập miễn phí.** Các tập có `episode_no` nhỏ hơn hoặc bằng `free_until_episode` là miễn phí. Đọc lại mỗi lần đồng bộ, vì giá trị này có thể đổi. - - **Sắp ra mắt.** Dòng có `"id": null` và `"status": "planned"` là chỗ giữ cho tập chưa phát hành. Hiển thị là "sắp ra mắt" và không bao giờ gửi sang playback. - - **Sẵn sàng.** Làm mờ hoặc ẩn các tập có `"stream_ready": false`. - - **Ảnh và chữ.** `poster_url` và `synopsis_full` có thể là `null`: hiện ảnh giữ chỗ, hoặc không hiện gì. `poster_uri` của tập không chắc là URL tải được, nên dùng poster của phim thay thế. - - **Phụ đề không nằm trong catalog.** Phụ đề đi kèm mỗi vé playback; xem [Giai đoạn 3](#phase-3). - - ### Cửa publish của riêng bạn {#publish-gate} - - Bạn quyết định khi nào một phim xuất hiện trong app. Một luật đơn giản tránh được ô trống hoặc ô hỏng: chỉ hiện phim khi có tên, có poster và ít nhất tập đầu có `"stream_ready": true`. Phim chưa qua luật vẫn giữ trong database và được kiểm lại ở lần đồng bộ sau. - - ### Phim và tập bị rút {#withdrawals} - - Một phim rời catalog khi giấy phép của bạn cho phim đó hết hạn hoặc bị tắt, hoặc khi phim bị rút. Một tập rời catalog khi bị rút. Không có thông báo nào: dòng đó chỉ đơn giản vắng mặt trong response kế tiếp. - - Khi một dòng vắng mặt: - - 1. Đánh dấu là không khả dụng trong database, ngừng hiển thị và ngừng bán. Đừng xoá: giao dịch mua và lịch sử xem của người xem vẫn trỏ tới nó. - 2. Nếu nó quay lại ở response sau, ví dụ khi gia hạn giấy phép, đánh dấu khả dụng trở lại. - 3. Nếu lệnh gọi lỗi (bất kỳ status nào khác `200`), giữ bản cũ và thử lại ở lần chạy sau. Không bao giờ coi lệnh gọi lỗi là catalog rỗng. - - Bản cũ không thể giúp ai xem được phim đã bị rút: mỗi request xin vé đều kiểm lại giấy phép, và câu trả lời của request xin vé mới là câu quyết định. - - **Xong khi:** app staging hiện các phim được cấp phép theo thứ tự của Wandura, lấy từ database của bạn, với tập miễn phí, ô "sắp ra mắt" và tập bị làm mờ hiển thị đúng. - - ## Giai đoạn 3: Luồng playback {#phase-3} - - Khi người xem chạm vào một tập, backend của bạn áp paywall của bạn trước. Chỉ khi người xem được phép xem, backend mới xin Wandura một vé. - - ```mermaid - sequenceDiagram - actor Viewer - participant App as Your app (Player SDK) - participant Backend as Your backend - participant API as Wandura Delivery API - participant Stream as Wandura streaming network - Viewer->>App: Taps an episode - App->>App: Player SDK gives device ID and device public key - App->>Backend: Play request (your session, episode, device values) - Backend->>Backend: Your paywall - free, unlocked or VIP? - alt Viewer may not watch - Backend-->>App: Locked - show your paywall - else Viewer may watch - Backend->>API: POST /api/delivery/v1/playback (intent play) - API->>API: Check licence, sign ticket, record play - API-->>Backend: vid, play_auth_token, expires_at, protection, subtitles - Backend->>Backend: Check protection is private-encrypted - Backend-->>App: vid, play_auth_token, subtitles - App->>Stream: Player SDK loads the encrypted stream - Stream-->>Viewer: Video plays - Backend->>API: Up to 2 requests for the next episodes (intent prefetch) - end - ``` - - ### 1. Kiểm paywall trước {#paywall-first} - - Wandura chỉ kiểm tổ chức của bạn có được phát phim đó hay không. Wandura không biết người xem của bạn, nên sẽ cấp vé cho bất kỳ tập nào của một phim được cấp phép. Giữ tập khoá ở trạng thái khoá là việc của backend bạn: không bao giờ xin vé cho tập người xem chưa mở khoá. - - ### 2. Xin vé từ server {#request-ticket} - - Backend gọi `POST /api/delivery/v1/playback` bằng key playback, gửi kèm tập (`episode_id`, hoặc `film_ref` và `episode_no`), hai giá trị thiết bị từ Player SDK (`union_info` và `drm_kek`), `viewer_ref` của riêng bạn và `"intent": "play"`. Request và response đầy đủ nằm ở [tham chiếu playback](reference/playback.md) và trang [Playback](concepts/playback.md). - - - Gửi giá trị thiết bị đúng như Player SDK sinh ra. Nếu một lệnh gọi SDK trả về rỗng, hãy sửa app thay vì gửi một chuỗi giữ chỗ. Xem [gửi giá trị thiết bị](concepts/playback.md#send-the-device-values). - - Đặt `viewer_ref` là một ID mờ của riêng bạn, ví dụ `<user-id>:<device-id>`. Không bao giờ đưa email hay tên người vào đó. - - Trước khi trả kết quả cho app, kiểm `protection` là `private-encrypted`. Nếu là giá trị khác, không phát và không bán tập đó, và liên hệ Wandura. - - ### 3. Phát trên thiết bị {#play-on-device} - - App chuyển `vid` và `play_auth_token` cho Player SDK rồi bắt đầu phát. SDK tự tải stream đã mã hoá và key của nó. Player video thông thường không phát được các tập này: nó tải playlist rồi đứng im. Làm đủ mọi bước cài đặt trong hướng dẫn Player SDK trên cổng (**Developers** → **Player SDK**); bỏ sót một bước thường chỉ lộ ra dưới dạng player không bao giờ chạy. - - ### 4. Prefetch hai tập kế tiếp {#prefetch} - - Phim ngắn được xem liền mạch, nên tập kế phải chạy ngay. Ngay sau khi tập hiện tại bắt đầu, backend xin vé cho tối đa hai tập kế tiếp, với `"intent": "prefetch"`, để app tải sẵn. - - - Xin chúng ngay trong request của tập hiện tại bằng `"next": 2` (tới ba vé trong một lượt gọi), hoặc bằng request riêng. Xem [Phát mượt khi tải cao](guides/smooth-playback.md#request-early). - - Áp paywall cho từng tập. Không prefetch tập người xem chưa mở khoá. - - Bỏ qua dòng giữ chỗ và các tập có `"stream_ready": false`. - - Prefetch không được đếm là lượt phát. Khi người xem thật sự chuyển sang tập kế, đó là một lần bắt đầu phát mới: xin vé cho tập đó với `"intent": "play"`, và prefetch hai tập sau nó. - - Mọi request, kể cả prefetch, đều tính vào [rate limit](concepts/rate-limits.md) của tổ chức bạn. Không bao giờ xin vé cho cả một phim. - - ### 5. Hết hạn và thử lại {#expiry-retry} - - Một vé có hiệu lực 30 phút; `expires_at` cho biết thời điểm chính xác. Đừng giữ vé giữa các lần bắt đầu phát. Khi Player SDK báo lỗi trong lúc phát, kể cả vé hết hạn: - - 1. Xin đúng một vé mới và nạp lại player ở vị trí hiện tại. - 2. Nếu request đó lỗi, đối chiếu `error_code` với những gì người xem thấy, theo bảng dưới. Thử lại một lần, không lặp. - - Vé prefetch hết hạn trước khi người xem tới tập đó thì chỉ cần thay bằng một request mới. - - ### 6. Phụ đề {#subtitles} - - Mỗi response xin vé liệt kê phụ đề của tập dưới dạng file WebVTT, mỗi ngôn ngữ một file. Danh sách rỗng nghĩa là chưa có phụ đề nào được gắn; đó không phải lỗi. URL phụ đề sống lâu hơn vé, nên bạn có thể cache theo từng tập; khi Wandura thay một phụ đề thì URL của nó đổi, nên hãy làm mới danh sách từ vé kế tiếp. Trong web player, tải file bằng `fetch` rồi tự thêm cue, thay vì dùng phần tử `<track>` với `crossorigin`. Xem [Phụ đề](concepts/playback.md#subtitles). - - ### Người xem thấy gì với mỗi câu trả lời {#viewer-messages} - - Rẽ nhánh theo `error_code`, luôn có nhánh mặc định cho mã chưa biết, và không bao giờ hiện chữ `error` của Wandura cho người xem. - - | Câu trả lời | Nghĩa là | Người xem thấy | Backend của bạn làm | - |---|---|---|---| - | Paywall của bạn báo khoá | Không gọi Wandura | Màn paywall hoặc màn mở khoá của bạn | Không làm gì | - | `200` | Đã cấp vé | Tập được phát | Kiểm `protection`, rồi prefetch | - | `403` `not_entitled` | Giấy phép cho phim này hiện không hiệu lực | "Phim này không còn khả dụng" | Ngừng bán phim, ghi log `reason`, đồng bộ lại catalog | - | `404` `not_ready` | Tập không tồn tại, đã bị rút hoặc chưa sẵn sàng | "Chưa khả dụng" | Đồng bộ lại catalog | - | `503` `not_ready` | Hiện chưa có bản phát được | "Chưa khả dụng, thử lại sau" | Thử lại sau | - | `400` `invalid_request` hoặc `invalid_device_info`, `409` `sdk_required` | Lỗi ở cách app đọc giá trị từ Player SDK | "Không tải được tập này" | Báo đội kỹ thuật; không thử lại | - | `401`, hoặc `403` không có `error_code` | Key sai, đã thu hồi hoặc thiếu scope | "Không tải được tập này" | Báo đội kỹ thuật; kiểm key | - | `503` `service_unavailable` | Wandura chưa kiểm được key kịp lúc; key không sai | "Không tải được tập này, thử lại" | Thử lại sau `Retry-After`, có backoff; đừng xoay key | - | `429` `rate_limited` | Quá nhiều request | "Hệ thống đang bận, thử lại sau giây lát" | Chờ hết `Retry-After`, rồi tìm vòng lặp gây ra | - | `502` | Lỗi tạm thời phía Wandura | "Không tải được tập này" | Thử lại có backoff, rồi dừng | - - Mọi mã lỗi kèm body chính xác nằm ở [Lỗi](concepts/errors.md#playback-errors). - - **Xong khi:** trên một iPhone thật và một điện thoại Android thật, tập miễn phí phát được kèm phụ đề, tập khoá hiện paywall mà không có lệnh gọi nào tới Wandura, và tập kế chạy ngay không phải chờ. - - ## Giai đoạn 4: Feed creative quảng cáo (tuỳ chọn) {#phase-4} - - Bỏ qua giai đoạn này nếu tổ chức của bạn không dựng creative quảng cáo từ phim Wandura trên partner.wandura.ai. Nếu có, hệ thống marketing của bạn có thể đồng bộ hồ sơ của từng creative đã duyệt. + ## Giai đoạn 0: Onboarding {#phase-0} - 1. Tạo key có scope `creatives:export` trên trang **Developers**. - 2. Đồng bộ tăng dần: lật trang `GET /api/delivery/v1/creatives` bằng `cursor`, giữ `updated_at` lớn nhất làm mốc, và gửi nó làm `updated_since` ở lần chạy sau. - 3. Lưu hồ sơ theo khoá `creative_id`, và ghi đè khi hồ sơ về lại. - 4. `rights.ends_at` là 00:00 UTC của ngày cuối cùng trong quyền export, và ngày đó vẫn được dùng: ngừng dùng creative sau khi ngày UTC đó kết thúc, tức tại `rights.ends_at + 86400`. Để kiểm một creative đang lưu, gọi `GET /api/delivery/v1/creatives/{id}`: `404` với `code` `4040` nghĩa là creative không còn khả dụng. + Tổ chức, thành viên, giấy phép phim, tổ chức test và bản dùng thử Player SDK, trong kênh Discord Wandura của team bạn. **Trang:** [Trước khi bắt đầu](before-you-start.md#get-onboarded). + **Xong khi:** developer của bạn mở được **Developers** trên partner.wandura.ai, và Wandura đã xác nhận các phim bạn được cấp phép. - Hồ sơ mô tả creative và không bao giờ chứa URL media. Hỏi Wandura cách file video hoàn chỉnh tới được hệ thống của bạn. Chi tiết: [Creative](concepts/creatives.md). + ## Giai đoạn 1: Key {#phase-1} - ## Giai đoạn 5: Kế hoạch test {#phase-5} + Mỗi hệ thống và mỗi môi trường một key, chỉ mang những scope cần thiết, do developer của bạn tạo trên **Developers**. **Trang:** [Xác thực](authentication.md#scopes), [Bảo mật](concepts/security.md). + **Xong khi:** mỗi hệ thống có key riêng trong secrets manager, và `GET /config` gọi từ server của bạn trả `200`. - Một QA có thể chạy danh sách này trên bản build staging, với backend staging, trong tổ chức bạn test (xem [Test và production](#test-and-production)). Dùng điện thoại thật để test playback. Không có sandbox, và mọi request xin vé đều được ghi nhận, kể cả request test: hãy đặt một tiền tố dễ nhận như `qa-` trong `viewer_ref` cho lưu lượng test, và báo Wandura tổ chức nào là tổ chức test của bạn. + ## Giai đoạn 2: Đồng bộ catalog {#phase-2} - **Key và bảo mật** + Một job chép catalog vào database của bạn mỗi 15–60 phút, phân trang an toàn, và không bao giờ xoá sạch bản sao của bạn khi gặp lỗi. **Trang:** [Đồng bộ catalog](guides/catalog-sync.md). + **Xong khi:** app của bạn hiện các phim được cấp phép từ chính database của bạn, đúng thứ tự của Wandura, với tập miễn phí và ô "sắp ra mắt" hiển thị đúng. - - [ ] Tìm chuỗi `wnd_live_` trong bản build iOS và Android. Không được có kết quả nào. - - [ ] Log backend không chứa nguyên API key nào và không chứa `play_auth_token`. - - [ ] Gọi catalog không có key trả `401`, gọi bằng key thiếu `metadata:read` trả `403`. Job của bạn phát cảnh báo và giữ bản cũ. + ## Giai đoạn 3: Playback và paywall {#phase-3} - **Catalog** + Endpoint xin vé của bạn: kiểm paywall của bạn trước, rồi gửi một request batch cho tập đó và tối đa hai tập kế tiếp đã mở khoá; mỗi lỗi có một thông báo cho người xem. **Trang:** [Luồng playback và paywall](guides/playback-flow.md), [Phát mượt khi tải cao](guides/smooth-playback.md), [Lỗi](concepts/errors.md). + **Xong khi:** tập bị khoá không bao giờ tới được Wandura, và mỗi lỗi đều ứng với một màn hình. - - [ ] Phim trong app khớp danh sách giấy phép mà Wandura đã xác nhận. - - [ ] Phim hiện đúng thứ tự như trong response của API. - - [ ] Các tập tới `free_until_episode` mở được không cần trả tiền; tập kế tiếp hiện paywall. - - [ ] Tập giữ chỗ hiện "sắp ra mắt" và không chạm được. - - [ ] Tập có `"stream_ready": false` bị làm mờ hoặc ẩn. - - [ ] Phim không có poster hiện ảnh giữ chỗ của bạn, không phải ô trống. - - [ ] Khi một lần đồng bộ lỗi (ví dụ chặn mạng của job), catalog trong app giữ nguyên. + ## Giai đoạn 4: Player SDK trong app {#phase-4} - **Playback** + Giá trị thiết bị, vé từ backend của bạn, playback, hết hạn vé và phục hồi, phụ đề. **Trang:** [Player SDK](player-sdk/index.md), [iOS](player-sdk/ios.md), [Android](player-sdk/android.md), [Phụ đề](guides/subtitles.md). + **Xong khi:** một tập miễn phí phát được kèm phụ đề trên một iPhone thật và một điện thoại Android thật. - - [ ] Tập miễn phí phát được trên một iPhone thật và một điện thoại Android thật. - - [ ] Phụ đề hiện ra, và đổi ngôn ngữ được. Tập không có phụ đề vẫn phát, không báo lỗi. - - [ ] Tập khoá hiện paywall, và log backend không có request xin vé nào cho tập đó. - - [ ] Sau khi mở khoá, chính tập đó phát được. - - [ ] Trong lúc một tập đang phát, backend xin vé hai tập kế với `"intent": "prefetch"`, và bỏ qua tập người xem chưa mở khoá. - - [ ] Chuyển sang tập kế thì tập đó chạy nhanh và có một request `"intent": "play"` mới. - - [ ] Tạm dừng hơn 30 phút rồi xem tiếp thì có đúng một vé mới và phát tiếp từ đúng vị trí cũ. - - [ ] Bật chế độ máy bay giữa tập rồi tắt đi, app hồi phục mà không crash. - - [ ] Một test backend gửi `"(null)"` làm giá trị thiết bị nhận về `400` `invalid_device_info` và phát cảnh báo. + Tuỳ chọn, làm lúc nào cũng được sau Giai đoạn 1: [Đồng bộ creative](guides/creatives-sync.md), [Đồng bộ video mở](guides/open-video-sync.md). - **Hết bản quyền** + ## Giai đoạn 5: Test {#phase-5} - - [ ] Nhờ Wandura, trong kênh Discord Wandura của team bạn, kết thúc giấy phép của một phim test trong tổ chức bạn test. Sau lần đồng bộ kế, phim bị ẩn, và request xin vé cho phim đó trả `403` `not_entitled`, app hiện là "không còn khả dụng". - - [ ] Người xem đã trả tiền cho phim đó thấy thông báo đã thống nhất với đội hỗ trợ của bạn. + Kế hoạch test, chạy trên điện thoại thật. **Trang:** [Test](guides/testing.md). + **Xong khi:** mọi mục trong kế hoạch test đều đạt trên bản build release. ## Giai đoạn 6: Go-live {#phase-6} - ### Checklist {#go-live-checklist} - - - [ ] Key production đã được cấp và lưu, tách khỏi key staging. - - [ ] Giấy phép Player SDK phủ đúng bundle ID và package name của app production. - - [ ] Wandura đã xác nhận danh sách phim được cấp phép cùng khung thời gian giấy phép của chúng. - - [ ] Job đồng bộ catalog chạy đúng lịch trên production, có cảnh báo khi lỗi. - - [ ] Paywall đọc `free_until_episode` từ catalog đã đồng bộ. - - [ ] Backend kiểm `protection` ở mọi vé. - - [ ] Mọi câu trả lời trong bảng ở Giai đoạn 3 đều có màn hình tương ứng, và mã chưa biết rơi vào nhánh mặc định. - - [ ] Runbook trực sự cố ghi rõ ai thu hồi key playback khi bị lộ (bất kỳ Admin hoặc Developer nào của tổ chức) và ai báo Wandura. - - [ ] Toàn bộ [kế hoạch test](#phase-5) đã qua trên bản build phát hành. - - ### Cần theo dõi gì {#monitoring} - - | Tín hiệu | Ở đâu | Vì sao | - |---|---|---| - | Tỷ lệ xin vé thành công, và số câu trả lời theo `error_code` | Metrics backend của bạn | `not_entitled` tăng vọt thường là một giấy phép vừa hết; `invalid_device_info` hoặc `sdk_required` tăng là một bản app mới làm hỏng phần nối Player SDK; `rate_limited` là một vòng lặp retry. | - | Câu trả lời `5xx` và độ trễ xin vé | Metrics backend của bạn | Thử lại có backoff, và báo Wandura nếu kéo dài. | - | Lần đồng bộ catalog thành công gần nhất, số phim và số tập phát được | Job đồng bộ | Job đứng thì app vẫn hiện phim đã bị rút; số tụt đột ngột thì nên nhắn Wandura. | - | "Last used" của từng key | Trang **Developers** | Tìm key không còn dùng để thu hồi. | - - ### Khi hết bản quyền {#rights-end} + Giấy phép trả phí, soát giới hạn, key production, giám sát và kế hoạch khi hết quyền. **Trang:** [Checklist go-live](production/go-live.md), [Quan sát hệ thống](production/observability.md), [Khi hết quyền](production/rights-end.md), [Xử lý sự cố](production/troubleshooting.md). + **Xong khi:** Wandura xác nhận go-live trong kênh của bạn. - - **Ngày kết thúc giấy phép.** Ngày cuối của khung được tính (UTC). Từ ngày hôm sau, phim vắng mặt khỏi catalog, và request xin vé cho phim đó trả `403` `not_entitled`. - - **Giấy phép bị tắt sớm, hoặc tổ chức bị tạm ngưng.** Request xin vé mới bị từ chối ngay. Tổ chức bị tạm ngưng cũng nhận `403` từ catalog. - - **Phiên đang phát.** Vé đã cấp không bao giờ được gia hạn. Thiết kế app sao cho playback có thể kết thúc bằng một lỗi player bất kỳ lúc nào, và làm theo các bước thử lại ở Giai đoạn 3. - - **Phía bạn.** Ngừng bán phim, áp chính sách hoàn tiền của bạn, và ngừng dùng creative của phim đó khi ngày UTC của `rights.ends_at` đã kết thúc. - - **Gia hạn.** Phim được gia hạn sẽ quay lại ở lần đồng bộ kế; đánh dấu khả dụng trở lại. + ## Các neo giữ lại từ hướng dẫn cũ {#old-anchors} - ## Liên hệ ai {#contact} + Link tới hướng dẫn một trang trước đây sẽ dẫn về đây. Những phần đã chuyển đi: - | Cần | Liên hệ | + | Chủ đề | Nay nằm ở | |---|---| - | Dựng tổ chức, giấy phép phim và ngày, giấy phép Player SDK, một lần test hết bản quyền | Wandura, trong kênh Discord Wandura của team bạn | - | Vai trò **Developer** cho developer mới | Admin của tổ chức bạn trên partner.wandura.ai | - | Mọi key, kể cả key playback: tạo, xoay vòng, thu hồi | Developer của bạn, trên trang **Developers** | - | Key playback có thể đã bị lộ | Một Admin hoặc Developer của tổ chức thu hồi trước, rồi báo Wandura | - | `5xx` lặp lại hoặc sự cố khác | Wandura, trong kênh Discord Wandura của team bạn, kèm các thông tin liệt kê ở [Hỗ trợ](help/support.md) | - - ## Liên quan - - - [Bắt đầu nhanh](quickstart.md): những lệnh gọi đầu tiên trong vài phút. - - [Catalog](concepts/catalog.md) và [Playback](concepts/playback.md): từng phần hoạt động thế nào. - - [Lỗi](concepts/errors.md) và [Rate limit](concepts/rate-limits.md). - - [FAQ](help/faq.md). + | Test và production, kế hoạch test | [Test](guides/testing.md) | + | Checklist go-live, giám sát, hết quyền | [Go-live](production/go-live.md), [Quan sát hệ thống](production/observability.md), [Khi hết quyền](production/rights-end.md) | + | Prefetch, hết hạn vé, phụ đề, thông báo cho người xem | [Luồng playback](guides/playback-flow.md), [Phụ đề](guides/subtitles.md), [Lỗi](concepts/errors.md#viewer-messages) | + | Lưu gì, phim bị rút | [Đồng bộ catalog](guides/catalog-sync.md) |
- 02/10/2026 · +1 −1 dòng
Xem thay đổi
⋯ Phim ngắn được xem liền mạch, nên tập kế phải chạy ngay. Ngay sau khi tập hiện tại bắt đầu, backend xin vé cho tối đa hai tập kế tiếp, với `"intent": "prefetch"`, để app tải sẵn. - - Mỗi request chỉ cho một tập, nên đây là tối đa hai request thêm. Không có request theo lô. + - Xin chúng ngay trong request của tập hiện tại bằng `"next": 2` (tới ba vé trong một lượt gọi), hoặc bằng request riêng. Xem [Phát mượt khi tải cao](guides/smooth-playback.md#request-early). - Áp paywall cho từng tập. Không prefetch tập người xem chưa mở khoá. - Bỏ qua dòng giữ chỗ và các tập có `"stream_ready": false`. ⋯
- 01/10/2026 · +8 −8 dòng
Xem thay đổi
⋯ | Quyền developer | Developer backend của bạn nhận vai trò **Developer**. Vai trò này chỉ mở trang **Developers**, nơi quản lý key. Admin của tổ chức cũng quản lý được key. | Email của các developer. | | Giấy phép phim | Một giấy phép streaming cho mỗi phim bạn được chiếu. Khung thời gian có thể có ngày bắt đầu, ngày kết thúc, cả hai hoặc không có ngày nào. | Danh sách phim và ngày trong thoả thuận. | - | Key playback | Một API key có scope `playback`. Chỉ Wandura cấp. | Môi trường nào cần key, ví dụ staging và production. | + | Key playback | Một API key có scope `playback`. Developer của bạn tự tạo trên trang **Developers**, mỗi môi trường một key. 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. | Không cần gì: bạn tự tạo. | | Giấy phép Player SDK | 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 đó. Kèm theo là quyền vào hướng dẫn Player SDK ở partner.wandura.ai → **Developers** → **Player SDK**. | Bundle ID iOS và package name Android mà app sẽ phát hành, không dùng ID tạm. | ⋯ Ngày của giấy phép tính theo nguyên ngày UTC, tính cả ngày đầu lẫn ngày cuối. Giấy phép không có ngày bắt đầu thì có hiệu lực ngay khi được cấp; không có ngày kết thúc thì chạy đến khi Wandura kết thúc nó. Wandura cũng có thể tắt một giấy phép trước ngày kết thúc. Bạn không cần tự theo dõi ngày: catalog chỉ liệt kê những phim có giấy phép đang hiệu lực hôm nay. - **Xong khi:** developer của bạn đăng nhập được partner.wandura.ai và mở được **Developers**, bạn đã nhận key playback và giấy phép Player SDK, và Wandura đã xác nhận danh sách phim được cấp phép. + **Xong khi:** developer của bạn đăng nhập được partner.wandura.ai và mở được **Developers**, bạn đã nhận giấy phép Player SDK, và Wandura đã xác nhận danh sách phim được cấp phép. Developer của bạn tự tạo key playback ở [Giai đoạn 1](#phase-1). ## Giai đoạn 1: Key và môi trường {#phase-1} ⋯ |---|---|---| | Job đồng bộ catalog | `metadata:read` | Developer của bạn, trên trang **Developers** | - | Dịch vụ playback (server xin vé) | `playback` | Wandura | + | Dịch vụ playback (server xin vé) | `playback` (kèm `metadata:read`: chọn **Stream films in an app**) | Developer của bạn, trên trang **Developers** | | Job đồng bộ cho marketing (chỉ khi dùng [Giai đoạn 4](#phase-4)) | `creatives:export` | Developer của bạn, trên trang **Developers** | ⋯ - Lưu key trong secrets manager và đọc qua biến môi trường. Không commit key, không đưa key vào app. - Staging và production dùng key khác nhau, để thu hồi một key mà không ảnh hưởng key kia. - - Key playback do Wandura xoay vòng, không xoay trên cổng. Để đổi không gián đoạn, Wandura tạo một key playback mới bên cạnh key cũ, bạn triển khai key mới, rồi Wandura thu hồi key cũ; trong lúc chuyển cả hai key đều chạy. Trên cổng, chỉ **Admin** của tổ chức thu hồi được key playback: đó là công tắc khẩn cấp khi bạn nghi key bị lộ. + - Nếu key playback bị lộ, bất kỳ ai cũng stream được phim bạn được cấp phép. Bất kỳ **Admin** hoặc **Developer** nào của tổ chức cũng xoay vòng hoặc thu hồi được key trên trang **Developers**: hãy thu hồi ngay nếu nghi key đã bị lộ. Để đổi không gián đoạn, tạo key playback thứ hai, triển khai nó, rồi thu hồi key cũ. Wandura được báo mỗi khi có key playback mới hoặc một key playback được xoay vòng. - Không bao giờ ghi log nguyên key hay `play_auth_token`. Khi trao đổi với Wandura, chỉ nêu tiền tố key hiện trên trang **Developers**. ⋯ - [ ] Backend kiểm `protection` ở mọi vé. - [ ] Mọi câu trả lời trong bảng ở Giai đoạn 3 đều có màn hình tương ứng, và mã chưa biết rơi vào nhánh mặc định. - - [ ] Runbook trực sự cố ghi rõ ai thu hồi key playback khi bị lộ (Admin của tổ chức) và ai báo Wandura. + - [ ] Runbook trực sự cố ghi rõ ai thu hồi key playback khi bị lộ (bất kỳ Admin hoặc Developer nào của tổ chức) và ai báo Wandura. - [ ] Toàn bộ [kế hoạch test](#phase-5) đã qua trên bản build phát hành. ⋯ | Cần | Liên hệ | |---|---| - | Dựng tổ chức, key playback và việc xoay vòng nó, giấy phép phim và ngày, giấy phép Player SDK, một lần test hết bản quyền | Wandura, trong kênh Discord Wandura của team bạn | + | Dựng tổ chức, giấy phép phim và ngày, giấy phép Player SDK, một lần test hết bản quyền | Wandura, trong kênh Discord Wandura của team bạn | | Vai trò **Developer** cho developer mới | Admin của tổ chức bạn trên partner.wandura.ai | - | Key bạn tự tạo (`metadata:read`, `creatives:export`) | Developer của bạn, trên trang **Developers** | - | Key playback có thể đã bị lộ | Admin của tổ chức thu hồi trước, rồi báo Wandura | + | Mọi key, kể cả key playback: tạo, xoay vòng, thu hồi | Developer của bạn, trên trang **Developers** | + | Key playback có thể đã bị lộ | Một Admin hoặc Developer của tổ chức thu hồi trước, rồi báo Wandura | | `5xx` lặp lại hoặc sự cố khác | Wandura, trong kênh Discord Wandura của team bạn, kèm các thông tin liệt kê ở [Hỗ trợ](help/support.md) | ⋯
- 01/10/2026 · +25 −16 dòng
Xem thay đổi
⋯ |---|---|---| | Phim | Sản xuất, mã hoá và bảo vệ mọi phim, mọi tập. Cập nhật tên, tóm tắt, poster, thể loại, thứ tự hiển thị và phụ đề. | Hiển thị trong app đúng thứ tự và đúng nội dung chữ nhận được. | - | Bản quyền | Cấp cho tổ chức của bạn giấy phép streaming theo từng phim, có ngày bắt đầu và ngày kết thúc, và kiểm tra ở mọi request xin vé. | Tuân thủ các giới hạn khác trong hợp đồng, ví dụ các quốc gia mà app được chiếu phim. | + | Bản quyền | Cấp cho tổ chức của bạn giấy phép streaming theo từng phim, có khung thời gian (ngày bắt đầu, ngày kết thúc, cả hai hoặc không có ngày nào), và kiểm tra ở mọi request xin vé. | Tuân thủ các giới hạn khác trong hợp đồng, ví dụ các quốc gia mà app được chiếu phim. | | Người xem và tiền | Không có gì. API không có định danh theo từng người xem. | Tài khoản, đăng nhập, paywall, tập miễn phí, xu, gói thuê bao, VIP, hoàn tiền và hỗ trợ người xem. | | Key | Cấp key phát được video. Cho developer của bạn tự tạo key chỉ đọc. | Giữ mọi key ở server, xoay vòng và thu hồi key, không bao giờ đưa key vào app. | - | Player | Cung cấp giấy phép Player SDK và đăng ký ID app của bạn. | Tích hợp Player SDK vào app và làm theo bộ tài liệu onboarding của SDK. | + | Player | Đă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 đó. | Tích hợp Player SDK vào app và làm theo hướng dẫn Player SDK trên cổng. | | Playback | Ký vé cho một tập trên một thiết bị, và ghi nhận lượt phát. | Chỉ xin vé cho tập người xem được phép xem, rồi chuyển vé cho player. | | Số liệu | Đếm lượt phát theo từng phim từ các request xin vé của bạn. | Đánh dấu request prefetch là prefetch, để không bị đếm thành lượt phát. | ⋯ ## Giai đoạn 0: Wandura dựng sẵn cho bạn những gì {#phase-0} - Trước khi developer của bạn viết dòng code nào, Wandura sẽ dựng sẵn các mục dưới đây. Hãy hỏi đúng tên từng mục. + Trước khi developer của bạn viết dòng code nào, Wandura sẽ dựng sẵn các mục dưới đây. Hãy hỏi đúng tên từng mục trong kênh Discord Wandura của team bạn; thứ tự các bước nằm ở [Onboarding](before-you-start.md#get-onboarded). | Mục | Là gì | Bạn gửi Wandura | ⋯ | Tổ chức | Không gian làm việc của đội bạn trên [partner.wandura.ai](https://partner.wandura.ai). Mọi key và giấy phép đều thuộc về nó. | Tên tổ chức và email của người sẽ làm **Admin**. | | Quyền developer | Developer backend của bạn nhận vai trò **Developer**. Vai trò này chỉ mở trang **Developers**, nơi quản lý key. Admin của tổ chức cũng quản lý được key. | Email của các developer. | - | Giấy phép phim | Một giấy phép streaming cho mỗi phim bạn được chiếu, có ngày bắt đầu và ngày kết thúc. | Danh sách phim và ngày trong thoả thuận. | + | Giấy phép phim | Một giấy phép streaming cho mỗi phim bạn được chiếu. Khung thời gian có thể có ngày bắt đầu, ngày kết thúc, cả hai hoặc không có ngày nào. | Danh sách phim và ngày trong thoả thuận. | | Key playback | Một API key có scope `playback`. Chỉ Wandura cấp. | Môi trường nào cần key, ví dụ staging và production. | - | Giấy phép Player SDK | Giấy phép cho Player SDK giải mã phim Wandura, gắn với ID app của bạn. Tổ chức của bạn trả tiền giấy phép này. | Bundle ID iOS và package name Android mà app sẽ phát hành, không dùng ID tạm. | + | Giấy phép Player SDK | 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 đó. Kèm theo là quyền vào hướng dẫn Player SDK ở partner.wandura.ai → **Developers** → **Player SDK**. | Bundle ID iOS và package name Android mà app sẽ phát hành, không dùng ID tạm. | Cách các vai trò hoạt động trên cổng được giải thích ở [Vai trò](../partners/roles.md). - Ngày của giấy phép tính theo nguyên ngày UTC, tính cả ngày đầu lẫn ngày cuối. Wandura cũng có thể tắt một giấy phép trước ngày kết thúc. Bạn không cần tự theo dõi ngày: catalog chỉ liệt kê những phim có giấy phép đang hiệu lực hôm nay. + Ngày của giấy phép tính theo nguyên ngày UTC, tính cả ngày đầu lẫn ngày cuối. Giấy phép không có ngày bắt đầu thì có hiệu lực ngay khi được cấp; không có ngày kết thúc thì chạy đến khi Wandura kết thúc nó. Wandura cũng có thể tắt một giấy phép trước ngày kết thúc. Bạn không cần tự theo dõi ngày: catalog chỉ liệt kê những phim có giấy phép đang hiệu lực hôm nay. **Xong khi:** developer của bạn đăng nhập được partner.wandura.ai và mở được **Developers**, bạn đã nhận key playback và giấy phép Player SDK, và Wandura đã xác nhận danh sách phim được cấp phép. ⋯ - Lưu key trong secrets manager và đọc qua biến môi trường. Không commit key, không đưa key vào app. - Staging và production dùng key khác nhau, để thu hồi một key mà không ảnh hưởng key kia. - - Key playback do Wandura xoay vòng, không xoay trên cổng. Chỉ **Admin** của tổ chức thu hồi được nó: đó là công tắc khẩn cấp khi bạn nghi key bị lộ. + - Key playback do Wandura xoay vòng, không xoay trên cổng. Để đổi không gián đoạn, Wandura tạo một key playback mới bên cạnh key cũ, bạn triển khai key mới, rồi Wandura thu hồi key cũ; trong lúc chuyển cả hai key đều chạy. Trên cổng, chỉ **Admin** của tổ chức thu hồi được key playback: đó là công tắc khẩn cấp khi bạn nghi key bị lộ. - Không bao giờ ghi log nguyên key hay `play_auth_token`. Khi trao đổi với Wandura, chỉ nêu tiền tố key hiện trên trang **Developers**. Tạo, xoay vòng và thu hồi key từng bước: [Key cho developer](../partners/developer-keys.md). + ### Test và production {#test-and-production} + + Không có sandbox. Staging và production gọi cùng một base URL, `https://www.wandura.ai`, và nhận cùng câu trả lời; thứ tách lưu lượng test ra là tổ chức và key. + + - **Tổ chức test.** Wandura quyết định bạn có test trong một tổ chức test riêng hay không. Tổ chức đó chạy như mọi tổ chức khác: thành viên, key và giấy phép phim riêng. + - **Phim để test.** Các phim bạn dùng để test được cấp giấy phép cho tổ chức bạn test. Hỏi chúng trong kênh Discord Wandura của team bạn. + - **Lượt phát test.** Mọi request xin vé đều được ghi nhận, kể cả request test. Đặt tiền tố như `qa-` trong `viewer_ref` cho lưu lượng test, và báo Wandura tổ chức nào là tổ chức test của bạn. + **Xong khi:** mỗi hệ thống backend có key riêng trong secrets manager, và một lệnh `GET /api/delivery/v1/catalog` từ server staging trả về `200`. ⋯ ### 3. Phát trên thiết bị {#play-on-device} - App chuyển `vid` và `play_auth_token` cho Player SDK rồi bắt đầu phát. SDK tự tải stream đã mã hoá và key của nó. Player video thông thường không phát được các tập này: nó tải playlist rồi đứng im. Làm đủ mọi bước cài đặt trong bộ tài liệu onboarding của Player SDK; bỏ sót một bước thường chỉ lộ ra dưới dạng player không bao giờ chạy. + App chuyển `vid` và `play_auth_token` cho Player SDK rồi bắt đầu phát. SDK tự tải stream đã mã hoá và key của nó. Player video thông thường không phát được các tập này: nó tải playlist rồi đứng im. Làm đủ mọi bước cài đặt trong hướng dẫn Player SDK trên cổng (**Developers** → **Player SDK**); bỏ sót một bước thường chỉ lộ ra dưới dạng player không bao giờ chạy. ### 4. Prefetch hai tập kế tiếp {#prefetch} ⋯ ### 6. Phụ đề {#subtitles} - Mỗi response xin vé liệt kê phụ đề của tập dưới dạng file WebVTT, mỗi ngôn ngữ một file. Danh sách rỗng nghĩa là chưa có phụ đề nào được gắn; đó không phải lỗi. URL phụ đề sống lâu hơn vé, nên bạn có thể cache theo từng tập. Trong web player, tải file bằng `fetch` rồi tự thêm cue, thay vì dùng phần tử `<track>` với `crossorigin`. Xem [Phụ đề](concepts/playback.md#subtitles). + Mỗi response xin vé liệt kê phụ đề của tập dưới dạng file WebVTT, mỗi ngôn ngữ một file. Danh sách rỗng nghĩa là chưa có phụ đề nào được gắn; đó không phải lỗi. URL phụ đề sống lâu hơn vé, nên bạn có thể cache theo từng tập; khi Wandura thay một phụ đề thì URL của nó đổi, nên hãy làm mới danh sách từ vé kế tiếp. Trong web player, tải file bằng `fetch` rồi tự thêm cue, thay vì dùng phần tử `<track>` với `crossorigin`. Xem [Phụ đề](concepts/playback.md#subtitles). ### Người xem thấy gì với mỗi câu trả lời {#viewer-messages} ⋯ | `400` `invalid_request` hoặc `invalid_device_info`, `409` `sdk_required` | Lỗi ở cách app đọc giá trị từ Player SDK | "Không tải được tập này" | Báo đội kỹ thuật; không thử lại | | `401`, hoặc `403` không có `error_code` | Key sai, đã thu hồi hoặc thiếu scope | "Không tải được tập này" | Báo đội kỹ thuật; kiểm key | + | `503` `service_unavailable` | Wandura chưa kiểm được key kịp lúc; key không sai | "Không tải được tập này, thử lại" | Thử lại sau `Retry-After`, có backoff; đừng xoay key | | `429` `rate_limited` | Quá nhiều request | "Hệ thống đang bận, thử lại sau giây lát" | Chờ hết `Retry-After`, rồi tìm vòng lặp gây ra | | `502` | Lỗi tạm thời phía Wandura | "Không tải được tập này" | Thử lại có backoff, rồi dừng | ⋯ 2. Đồng bộ tăng dần: lật trang `GET /api/delivery/v1/creatives` bằng `cursor`, giữ `updated_at` lớn nhất làm mốc, và gửi nó làm `updated_since` ở lần chạy sau. 3. Lưu hồ sơ theo khoá `creative_id`, và ghi đè khi hồ sơ về lại. - 4. Ngừng dùng creative khi đã qua `rights.ends_at`. Để kiểm một creative đang lưu, gọi `GET /api/delivery/v1/creatives/{id}`: `404` với `code` `4040` nghĩa là creative không còn khả dụng. + 4. `rights.ends_at` là 00:00 UTC của ngày cuối cùng trong quyền export, và ngày đó vẫn được dùng: ngừng dùng creative sau khi ngày UTC đó kết thúc, tức tại `rights.ends_at + 86400`. Để kiểm một creative đang lưu, gọi `GET /api/delivery/v1/creatives/{id}`: `404` với `code` `4040` nghĩa là creative không còn khả dụng. Hồ sơ mô tả creative và không bao giờ chứa URL media. Hỏi Wandura cách file video hoàn chỉnh tới được hệ thống của bạn. Chi tiết: [Creative](concepts/creatives.md). ⋯ ## Giai đoạn 5: Kế hoạch test {#phase-5} - Một QA có thể chạy danh sách này trên bản build staging, với backend staging. Dùng điện thoại thật để test playback. Mọi request xin vé đều được ghi nhận, kể cả request test, nên hãy đặt một tiền tố dễ nhận như `qa-` trong `viewer_ref` cho lưu lượng test. + Một QA có thể chạy danh sách này trên bản build staging, với backend staging, trong tổ chức bạn test (xem [Test và production](#test-and-production)). Dùng điện thoại thật để test playback. Không có sandbox, và mọi request xin vé đều được ghi nhận, kể cả request test: hãy đặt một tiền tố dễ nhận như `qa-` trong `viewer_ref` cho lưu lượng test, và báo Wandura tổ chức nào là tổ chức test của bạn. **Key và bảo mật** ⋯ **Hết bản quyền** - - [ ] Nhờ Wandura kết thúc giấy phép của một phim test. Sau lần đồng bộ kế, phim bị ẩn, và request xin vé cho phim đó trả `403` `not_entitled`, app hiện là "không còn khả dụng". + - [ ] Nhờ Wandura, trong kênh Discord Wandura của team bạn, kết thúc giấy phép của một phim test trong tổ chức bạn test. Sau lần đồng bộ kế, phim bị ẩn, và request xin vé cho phim đó trả `403` `not_entitled`, app hiện là "không còn khả dụng". - [ ] Người xem đã trả tiền cho phim đó thấy thông báo đã thống nhất với đội hỗ trợ của bạn. ⋯ - [ ] Key production đã được cấp và lưu, tách khỏi key staging. - [ ] Giấy phép Player SDK phủ đúng bundle ID và package name của app production. - - [ ] Wandura đã xác nhận danh sách phim được cấp phép cùng ngày bắt đầu và ngày kết thúc. + - [ ] Wandura đã xác nhận danh sách phim được cấp phép cùng khung thời gian giấy phép của chúng. - [ ] Job đồng bộ catalog chạy đúng lịch trên production, có cảnh báo khi lỗi. - [ ] Paywall đọc `free_until_episode` từ catalog đã đồng bộ. ⋯ - **Giấy phép bị tắt sớm, hoặc tổ chức bị tạm ngưng.** Request xin vé mới bị từ chối ngay. Tổ chức bị tạm ngưng cũng nhận `403` từ catalog. - **Phiên đang phát.** Vé đã cấp không bao giờ được gia hạn. Thiết kế app sao cho playback có thể kết thúc bằng một lỗi player bất kỳ lúc nào, và làm theo các bước thử lại ở Giai đoạn 3. - - **Phía bạn.** Ngừng bán phim, áp chính sách hoàn tiền của bạn, và ngừng dùng creative của phim đó sau `rights.ends_at`. + - **Phía bạn.** Ngừng bán phim, áp chính sách hoàn tiền của bạn, và ngừng dùng creative của phim đó khi ngày UTC của `rights.ends_at` đã kết thúc. - **Gia hạn.** Phim được gia hạn sẽ quay lại ở lần đồng bộ kế; đánh dấu khả dụng trở lại. ⋯ | Cần | Liên hệ | |---|---| - | Dựng tổ chức, key playback và việc xoay vòng nó, giấy phép phim và ngày, giấy phép Player SDK, một lần test hết bản quyền | Wandura | + | Dựng tổ chức, key playback và việc xoay vòng nó, giấy phép phim và ngày, giấy phép Player SDK, một lần test hết bản quyền | Wandura, trong kênh Discord Wandura của team bạn | | Vai trò **Developer** cho developer mới | Admin của tổ chức bạn trên partner.wandura.ai | | Key bạn tự tạo (`metadata:read`, `creatives:export`) | Developer của bạn, trên trang **Developers** | | Key playback có thể đã bị lộ | Admin của tổ chức thu hồi trước, rồi báo Wandura | - | `5xx` lặp lại hoặc sự cố khác | Wandura, kèm các thông tin liệt kê ở [Hỗ trợ](help/support.md) | + | `5xx` lặp lại hoặc sự cố khác | Wandura, trong kênh Discord Wandura của team bạn, kèm các thông tin liệt kê ở [Hỗ trợ](help/support.md) | ## Liên quan ⋯
- 01/10/2026 · +12 −12 dòng
Xem thay đổi
⋯ ## Giai đoạn 0: Wandura dựng sẵn cho bạn những gì {#phase-0} - Trước khi developer của bạn viết dòng code nào, đầu mối đối tác Wandura sẽ dựng sẵn các mục dưới đây. Hãy hỏi đúng tên từng mục. + Trước khi developer của bạn viết dòng code nào, Wandura sẽ dựng sẵn các mục dưới đây. Hãy hỏi đúng tên từng mục. | Mục | Là gì | Bạn gửi Wandura | ⋯ | Giấy phép phim | Một giấy phép streaming cho mỗi phim bạn được chiếu, có ngày bắt đầu và ngày kết thúc. | Danh sách phim và ngày trong thoả thuận. | | Key playback | Một API key có scope `playback`. Chỉ Wandura cấp. | Môi trường nào cần key, ví dụ staging và production. | - | Giấy phép Player SDK | Giấy phép cho Player SDK giải mã phim Wandura, gắn với ID app của bạn. | Bundle ID iOS và package name Android mà app sẽ phát hành, không dùng ID tạm. | + | Giấy phép Player SDK | Giấy phép cho Player SDK giải mã phim Wandura, gắn với ID app của bạn. Tổ chức của bạn trả tiền giấy phép này. | Bundle ID iOS và package name Android mà app sẽ phát hành, không dùng ID tạm. | Cách các vai trò hoạt động trên cổng được giải thích ở [Vai trò](../partners/roles.md). ⋯ Ngày của giấy phép tính theo nguyên ngày UTC, tính cả ngày đầu lẫn ngày cuối. Wandura cũng có thể tắt một giấy phép trước ngày kết thúc. Bạn không cần tự theo dõi ngày: catalog chỉ liệt kê những phim có giấy phép đang hiệu lực hôm nay. - **Xong khi:** developer của bạn đăng nhập được partner.wandura.ai và mở được **Developers**, bạn đã nhận key playback và giấy phép Player SDK, và đầu mối đã xác nhận danh sách phim được cấp phép. + **Xong khi:** developer của bạn đăng nhập được partner.wandura.ai và mở được **Developers**, bạn đã nhận key playback và giấy phép Player SDK, và Wandura đã xác nhận danh sách phim được cấp phép. ## Giai đoạn 1: Key và môi trường {#phase-1} ⋯ ### Bao lâu chạy một lần {#sync-frequency} - Chạy job mỗi 15 đến 60 phút, và cho phép người trong đội bấm chạy tay khi đầu mối báo có phim mới. Catalog không gửi thông báo thay đổi, nên hỏi định kỳ là cách để thấy thay đổi. Đừng gọi catalog mỗi lần mở app: hãy phục vụ nó từ server của bạn. + Chạy job mỗi 15 đến 60 phút, và cho phép người trong đội bấm chạy tay khi Wandura báo có phim mới. Catalog không gửi thông báo thay đổi, nên hỏi định kỳ là cách để thấy thay đổi. Đừng gọi catalog mỗi lần mở app: hãy phục vụ nó từ server của bạn. ### Không có cursor, không phân trang {#no-pagination} ⋯ 4. Ngừng dùng creative khi đã qua `rights.ends_at`. Để kiểm một creative đang lưu, gọi `GET /api/delivery/v1/creatives/{id}`: `404` với `code` `4040` nghĩa là creative không còn khả dụng. - Hồ sơ mô tả creative và không bao giờ chứa URL media. Hỏi đầu mối đối tác Wandura cách file video hoàn chỉnh tới được hệ thống của bạn. Chi tiết: [Creative](concepts/creatives.md). + Hồ sơ mô tả creative và không bao giờ chứa URL media. Hỏi Wandura cách file video hoàn chỉnh tới được hệ thống của bạn. Chi tiết: [Creative](concepts/creatives.md). ## Giai đoạn 5: Kế hoạch test {#phase-5} ⋯ **Catalog** - - [ ] Phim trong app khớp danh sách giấy phép mà đầu mối Wandura đã xác nhận. + - [ ] Phim trong app khớp danh sách giấy phép mà Wandura đã xác nhận. - [ ] Phim hiện đúng thứ tự như trong response của API. - [ ] Các tập tới `free_until_episode` mở được không cần trả tiền; tập kế tiếp hiện paywall. ⋯ **Hết bản quyền** - - [ ] Nhờ đầu mối Wandura kết thúc giấy phép của một phim test. Sau lần đồng bộ kế, phim bị ẩn, và request xin vé cho phim đó trả `403` `not_entitled`, app hiện là "không còn khả dụng". + - [ ] Nhờ Wandura kết thúc giấy phép của một phim test. Sau lần đồng bộ kế, phim bị ẩn, và request xin vé cho phim đó trả `403` `not_entitled`, app hiện là "không còn khả dụng". - [ ] Người xem đã trả tiền cho phim đó thấy thông báo đã thống nhất với đội hỗ trợ của bạn. ⋯ - [ ] Key production đã được cấp và lưu, tách khỏi key staging. - [ ] Giấy phép Player SDK phủ đúng bundle ID và package name của app production. - - [ ] Đầu mối Wandura đã xác nhận danh sách phim được cấp phép cùng ngày bắt đầu và ngày kết thúc. + - [ ] Wandura đã xác nhận danh sách phim được cấp phép cùng ngày bắt đầu và ngày kết thúc. - [ ] Job đồng bộ catalog chạy đúng lịch trên production, có cảnh báo khi lỗi. - [ ] Paywall đọc `free_until_episode` từ catalog đã đồng bộ. ⋯ | Tỷ lệ xin vé thành công, và số câu trả lời theo `error_code` | Metrics backend của bạn | `not_entitled` tăng vọt thường là một giấy phép vừa hết; `invalid_device_info` hoặc `sdk_required` tăng là một bản app mới làm hỏng phần nối Player SDK; `rate_limited` là một vòng lặp retry. | | Câu trả lời `5xx` và độ trễ xin vé | Metrics backend của bạn | Thử lại có backoff, và báo Wandura nếu kéo dài. | - | Lần đồng bộ catalog thành công gần nhất, số phim và số tập phát được | Job đồng bộ | Job đứng thì app vẫn hiện phim đã bị rút; số tụt đột ngột thì nên nhắn đầu mối. | + | Lần đồng bộ catalog thành công gần nhất, số phim và số tập phát được | Job đồng bộ | Job đứng thì app vẫn hiện phim đã bị rút; số tụt đột ngột thì nên nhắn Wandura. | | "Last used" của từng key | Trang **Developers** | Tìm key không còn dùng để thu hồi. | ⋯ | Cần | Liên hệ | |---|---| - | Dựng tổ chức, key playback và việc xoay vòng nó, giấy phép phim và ngày, giấy phép Player SDK, một lần test hết bản quyền | Đầu mối đối tác Wandura của bạn | + | Dựng tổ chức, key playback và việc xoay vòng nó, giấy phép phim và ngày, giấy phép Player SDK, một lần test hết bản quyền | Wandura | | Vai trò **Developer** cho developer mới | Admin của tổ chức bạn trên partner.wandura.ai | | Key bạn tự tạo (`metadata:read`, `creatives:export`) | Developer của bạn, trên trang **Developers** | - | Key playback có thể đã bị lộ | Admin của tổ chức thu hồi trước, rồi báo đầu mối đối tác Wandura | - | `5xx` lặp lại hoặc sự cố khác | Đầu mối đối tác Wandura, kèm các thông tin liệt kê ở [Hỗ trợ](help/support.md) | + | Key playback có thể đã bị lộ | Admin của tổ chức thu hồi trước, rồi báo Wandura | + | `5xx` lặp lại hoặc sự cố khác | Wandura, kèm các thông tin liệt kê ở [Hỗ trợ](help/support.md) | ## Liên quan ⋯
- 30/09/2026 · +1 −1 dòng
Xem thay đổi
# Tích hợp app của bạn - > **TL;DR** — Server của bạn đồng bộ catalog Wandura 15–60 phút một lần vào database của bạn. Khi người xem bấm phát, app kiểm paywall của chính bạn, server xin Wandura vé cho đúng tập đó (và tối đa 2 tập kế để phát liền), rồi Player SDK được cấp phép phát. Bạn không bao giờ cầm key kho video của Wandura: mỗi vé đều được kiểm theo giấy phép của bạn và được Wandura ghi nhận. Go-live = [checklist ở giai đoạn 6](#go-live-checklist). Mô hình khác? Xem [Chọn mô hình tích hợp](integration-models.md). + > **TL;DR** — Server của bạn đồng bộ catalog Wandura 15–60 phút một lần vào database của bạn. Khi người xem bấm phát, app kiểm paywall của chính bạn, server xin Wandura vé cho đúng tập đó (và tối đa 2 tập kế để phát liền), rồi Player SDK được cấp phép phát. Bạn không bao giờ cầm key kho video của Wandura: mỗi vé đều được kiểm theo giấy phép của bạn và được Wandura ghi nhận. Go-live = [checklist ở giai đoạn 6](#go-live-checklist). Mô hình khác? Xem [Chọn mô hình tích hợp](integration-models.md). Checklist và giá license: [Trước khi bắt đầu](before-you-start.md). Hướng dẫn này đưa đội của bạn từ lúc ký thoả thuận đến khi app chạy thật và phát được phim Wandura. Các bước đi theo đúng thứ tự của một lần tích hợp thật: những gì Wandura dựng sẵn cho bạn, key, job đồng bộ catalog ở backend, luồng playback, feed creative quảng cáo (tuỳ chọn), kế hoạch test và checklist go-live. Mỗi giai đoạn trỏ sang trang tham chiếu để xem chi tiết. ⋯
- 30/09/2026 · +1 −1 dòng
Xem thay đổi
# Tích hợp app của bạn - > **TL;DR** — Server của bạn đồng bộ catalog Wandura 15–60 phút một lần vào database của bạn. Khi người xem bấm phát, app kiểm paywall của chính bạn, server xin Wandura vé cho đúng tập đó (và tối đa 2 tập kế để phát liền), rồi Player SDK được cấp phép phát. Bạn không bao giờ cầm key kho video của Wandura: mỗi vé đều được kiểm theo giấy phép của bạn và được Wandura ghi nhận. Go-live = [checklist ở giai đoạn 6](#go-live-checklist). + > **TL;DR** — Server của bạn đồng bộ catalog Wandura 15–60 phút một lần vào database của bạn. Khi người xem bấm phát, app kiểm paywall của chính bạn, server xin Wandura vé cho đúng tập đó (và tối đa 2 tập kế để phát liền), rồi Player SDK được cấp phép phát. Bạn không bao giờ cầm key kho video của Wandura: mỗi vé đều được kiểm theo giấy phép của bạn và được Wandura ghi nhận. Go-live = [checklist ở giai đoạn 6](#go-live-checklist). Mô hình khác? Xem [Chọn mô hình tích hợp](integration-models.md). Hướng dẫn này đưa đội của bạn từ lúc ký thoả thuận đến khi app chạy thật và phát được phim Wandura. Các bước đi theo đúng thứ tự của một lần tích hợp thật: những gì Wandura dựng sẵn cho bạn, key, job đồng bộ catalog ở backend, luồng playback, feed creative quảng cáo (tuỳ chọn), kế hoạch test và checklist go-live. Mỗi giai đoạn trỏ sang trang tham chiếu để xem chi tiết. ⋯
- 29/09/2026 · +2 −0 dòng
Xem thay đổi
# Tích hợp app của bạn + > **TL;DR** — Server của bạn đồng bộ catalog Wandura 15–60 phút một lần vào database của bạn. Khi người xem bấm phát, app kiểm paywall của chính bạn, server xin Wandura vé cho đúng tập đó (và tối đa 2 tập kế để phát liền), rồi Player SDK được cấp phép phát. Bạn không bao giờ cầm key kho video của Wandura: mỗi vé đều được kiểm theo giấy phép của bạn và được Wandura ghi nhận. Go-live = [checklist ở giai đoạn 6](#go-live-checklist). + Hướng dẫn này đưa đội của bạn từ lúc ký thoả thuận đến khi app chạy thật và phát được phim Wandura. Các bước đi theo đúng thứ tự của một lần tích hợp thật: những gì Wandura dựng sẵn cho bạn, key, job đồng bộ catalog ở backend, luồng playback, feed creative quảng cáo (tuỳ chọn), kế hoạch test và checklist go-live. Mỗi giai đoạn trỏ sang trang tham chiếu để xem chi tiết. ⋯
- 29/09/2026 · Tạo trang