Playback

Để phát một tập, backend của bạn xin Wandura vé playback bằng POST /api/delivery/v1/playback, và Player SDK của người xem dùng vé đó để tải stream đã mã hoá. Trang này giải thích cách xin vé, vé chứa gì, hiệu lực bao lâu và phải làm gì khi vé hết hạn.

Khi nào xin vé

Xin một vé cho mỗi lần bắt đầu phát: khi người xem chạm vào một tập, hoặc khi app tải trước tập kế tiếp. Đừng xin vé hàng loạt rồi lưu lại, vì mỗi vé hết hạn 30 phút sau khi được cấp.

Mỗi request chỉ dành cho đúng một tập. Không có endpoint batch.

Wandura kiểm tra giấy phép của bạn ở mọi request: tổ chức của bạn phải đang hoạt động, và giấy phép streaming cho phim phải đang hoạt động và nằm trong khung thời gian. Có mặt trong catalog không đảm bảo được cấp vé; request xin vé là bước kiểm tra cuối cùng.

Xác định tập

Bạn có thể chỉ định tập theo một trong hai cách:

Cách	Trường	Ví dụ
Theo episode ID	`episode_id`	`"episode_id": "b2a4d6e8-1c3f-4a5b-8d7e-9f0a1b2c3d4e"`
Theo phim và số tập	`film_ref` (film ID hoặc slug) và `episode_no` (số JSON, bắt đầu từ 1)	`"film_ref": "the-heiress-returns", "episode_no": 3`

Nếu gửi cả hai, episode_id được dùng. Phim không tồn tại, tập không tồn tại và tập chưa sẵn sàng đều trả về cùng một 404 với error_code not_ready.

Gửi giá trị thiết bị

Các tập được cấp phép đều đã mã hoá, và chỉ Player SDK giải mã được. Một HLS player thông thường sẽ tải playlist rồi đứng hình, không có lỗi nào giải thích lý do. Trước mỗi request xin vé, app trên thiết bị người xem lấy hai giá trị từ Player SDK và chuyển về backend của bạn:

Trường	Là gì
`union_info`	Device ID do Player SDK tạo ra.
`drm_kek`	Device public key do Player SDK tạo ra. Private key tương ứng không bao giờ rời khỏi thiết bị.

Hướng dẫn Player SDK ở partner.wandura.ai → Developers → Player SDK ghi rõ các lệnh gọi SDK cụ thể; hướng dẫn có sau khi onboarding, cho thành viên vai Developer hoặc Admin. 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 đó.

Quy tắc cho giá trị thiết bị:

Gửi cả hai hoặc không gửi cái nào. Chỉ gửi một giá trị sẽ trả 400 invalid_request.
Gửi đúng output thật của SDK. Một giá trị bị từ chối bằng 400 invalid_device_info khi, sau khi bỏ khoảng trắng hai đầu, nó ngắn hơn 8 ký tự hoặc là một trong (null), null, nil, undefined, nan, <null>, none (chữ hoa hay thường đều tính). Response liệt kê các trường sai trong fields. Thường điều này có nghĩa là một lệnh gọi SDK không trả về gì và code của bạn đã biến nó thành chuỗi.
Không gửi cả hai cho một tập đã mã hoá sẽ trả 409 sdk_required.

Vé chứa gì

Trường	Mô tả
`vid`	Video ID để tải trong Player SDK.
`play_auth_token`	Play token để đưa cho Player SDK. Hãy coi nó là secret.
`expires_at`	Thời điểm vé hết hạn, dạng timestamp ISO 8601 theo UTC.
`protection`	Mức bảo vệ của nội dung bạn nhận được. `private-encrypted` với các tập được cấp phép.
`subtitles`	Mọi phụ đề gắn với tập. Có thể là mảng rỗng.

Trên thiết bị, đặt video ID và play token cho Player SDK rồi bắt đầu phát. SDK tự tải playlist và các khoá giải mã được tham chiếu trong đó; code của bạn không phải xử lý khoá.

Kiểm tra `protection`

Đọc protection ở mọi response. Chỉ bán tập trả phí khi giá trị là private-encrypted. Nếu bạn nhận được giá trị khác, đừng bán tập đó và hãy liên hệ Wandura.

Thời hạn

Vé có hiệu lực 30 phút kể từ lúc được cấp. expires_at cho biết hạn chót chính xác.

Khi Player SDK báo lỗi trong lúc phát, kể cả khi vé hết hạn:

Xin một vé mới từ backend và tải lại player tại vị trí hiện tại.
Nếu request đó thất bại, đọc error_code trong response của API để quyết định thông báo gì cho người xem. Xem Lỗi.

Đừng dựa vào mã lỗi riêng của Player SDK để phát hiện vé hết hạn; chúng khác nhau giữa các phiên bản SDK. Retry một lần, không retry theo vòng lặp.

Lượt phát, prefetch và `intent`

Mỗi request xin vé thành công được ghi nhận phía Wandura và tính là một lượt phát, trừ khi được đánh dấu là prefetch. Nếu app tải tập trước khi người xem chạm vào, hãy báo cho Wandura bằng trường tuỳ chọn intent:

Giá trị	Ý nghĩa
`play`	Người xem vừa chạm vào tập.
`prefetch`	App đang tải tập trước khi người xem chạm. Không tính là lượt phát.

intent không bao giờ làm thay đổi response. Giá trị bị thiếu hoặc viết sai được ghi nhận là không xác định, không bị từ chối, và request đó vẫn tính là một lượt phát: chỉ prefetch được loại khỏi số lượt phát. Request prefetch vẫn tính vào rate limit của bạn.

`viewer_ref`

viewer_ref là một chuỗi opaque tuỳ chọn mà Wandura lưu cùng vé để tra cứu khi hỗ trợ. Hãy dùng định danh phiên hoặc thiết bị của riêng bạn, ví dụ <user-id>:<device-id>. Đừng đưa dữ liệu cá nhân như email hay tên vào đây.

Phụ đề

subtitles có một phần tử cho mỗi phụ đề gắn với tập:

Trường	Mô tả
`lang`	Mã ngôn ngữ đúng như studio giao, ví dụ `en`, `vi` hoặc `pt-BR`.
`url`	Địa chỉ tải file phụ đề.
`format`	Luôn là `webvtt`.

Mảng rỗng nghĩa là chưa có phụ đề nào được gắn. Đó không phải lỗi.
URL phụ đề không gắn với thời hạn của vé, nên bạn vẫn dùng được sau khi vé hết hạn. Khi Wandura thay một file phụ đề, file mới có URL mới và URL cũ thôi chạy: nếu URL đã lưu bị lỗi, hãy lấy URL hiện tại từ một vé mới.
Player native có thể nhận URL trực tiếp. Trong web player, đừng thêm thuộc tính crossorigin vào thẻ video để tải phụ đề bằng <track>: việc đó thay đổi cách chính video được request và có thể khiến video không phát được. Thay vào đó, hãy tải file WebVTT bằng fetch và thêm cue bằng video.addTextTrack().

Playback

Khi nào xin vé

Xác định tập

Gửi giá trị thiết bị

Vé chứa gì

Kiểm tra `protection`

Thời hạn

Lượt phát, prefetch và `intent`

`viewer_ref`

Phụ đề

Liên quan

Gửi góp ý

Playback

Khi nào xin vé#

Xác định tập#

Gửi giá trị thiết bị#

Vé chứa gì#

Kiểm tra protection#

Thời hạn#

Lượt phát, prefetch và intent#

viewer_ref#

Phụ đề#

Liên quan#

Khi nào xin vé

Xác định tập

Gửi giá trị thiết bị

Vé chứa gì

Kiểm tra `protection`

Thời hạn

Lượt phát, prefetch và `intent`

`viewer_ref`

Phụ đề

Liên quan