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. Mô hình khác? Xem Chọn mô hình tích hợp. Checklist và giá license: Trước khi bắt đầu.

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.

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é.

Ai làm gì#

Giai đoạn 0: Wandura dựng sẵn cho bạn những gì#

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.

Cách các vai trò hoạt động trên cổng được giải thích ở Vai trò.

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.

Giai đoạn 1: Key và môi trường#

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.

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:

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.

Test và 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#

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.

Bao lâu chạy một lầ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#

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ì#

Mọi trường được mô tả trong tham chiếu catalog. 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.

Cửa publish của riêng bạn#

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#

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#

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é.

1. Kiểm paywall trước#

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#

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 và trang Playback.

• 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ị.
• Đặ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ị#

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#

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ô.
• Á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 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#

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ụ đề#

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ụ đề.

Người xem thấy gì với mỗi câu trả lời#

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.

Mọi mã lỗi kèm body chính xác nằm ở Lỗi.

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)#

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.

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.

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.

Giai đoạn 5: Kế hoạch 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). 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

• 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ũ.

Catalog

• 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.

Playback

• 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.

Hết bản quyền

• 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.

Giai đoạn 6: 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 đã qua trên bản build phát hành.

Cần theo dõi gì#

Khi hết bản quyề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.

Liên hệ ai#

Liên quan#

• Bắt đầu nhanh: những lệnh gọi đầu tiên trong vài phút.
• Catalog và Playback: từng phần hoạt động thế nào.
• Lỗi và Rate limit.
• FAQ.