Catalog

Catalog là danh sách phim và tập mà tổ chức của bạn được phép stream ngay lúc này. Catalog được thiết kế để là danh sách phim duy nhất app của bạn cần: nó mang thứ tự hiển thị, quy tắc tập miễn phí, facet thể loại và cờ sẵn sàng cho từng tập, nên bạn không phải tự duy trì những thứ này.

Catalog chứa gì#

GET /api/delivery/v1/catalog trả về một phim khi tất cả các điều kiện sau đều đúng tại thời điểm request:

• Tổ chức của bạn có giấy phép streaming cho phim, và giấy phép đó đang hoạt động.
• Hôm nay nằm trong khung thời gian của giấy phép. Khung thời gian tính theo ngày trọn vẹn theo UTC, bao gồm cả ngày đầu và ngày cuối.
• Phim đã được publish.

Với những phim đó, catalog trả về mọi tập đã publish. Phim còn đang sản xuất, và bản dựng thô (review cut) được chia sẻ để bạn góp ý, không bao giờ xuất hiện trong catalog và không phát được qua API.

Catalog chỉ chứa metadata. Nó không bao giờ chứa URL video; bạn xin playback cho từng tập bằng POST /playback.

Cấu trúc response#

Response có hai mảng phẳng, films và episodes. Nối chúng theo episodes[].film_id = films[].id. Danh sách trường đầy đủ nằm trong tài liệu tham chiếu catalog.

Toàn bộ catalog trả về trong một response. Không có pagination.

Thứ tự#

films được sắp theo display_order, nhỏ nhất trước. Hãy hiển thị phim đúng theo thứ tự nhận được. Wandura chỉnh thứ tự này, nên đừng giữ bảng thứ tự riêng.

episodes được nhóm theo film ID, rồi sắp theo episode_no. Các nhóm không theo thứ tự hiển thị, nên hãy lấy thứ tự phim từ films.

Tập miễn phí và tập trả phí#

Tập có episode_no nhỏ hơn hoặc bằng free_until_episode của phim là miễn phí; các tập còn lại là trả phí. Giá trị này khác nhau giữa các phim và có thể thay đổi, nên hãy đọc từ catalog thay vì hard-code. 0 nghĩa là không có tập miễn phí; null nghĩa là phim chưa được đặt số này, nên hãy coi mọi tập là trả phí.

Tập dự kiến#

planned_episodes là số tập phim sẽ có. Khi một số tập chưa được publish, catalog vẫn có một dòng cho mỗi số tập còn thiếu để bạn hiển thị ô "sắp ra mắt". Các dòng placeholder này có:

Không bao giờ gửi dòng placeholder tới POST /playback: nó không có episode ID. Nếu phim có nhiều tập đã publish hơn planned_episodes, tất cả vẫn được trả về. Khi planned_episodes là null, phim không có dòng placeholder nào.

Trạng thái sẵn sàng: stream_ready#

stream_ready: true nghĩa là đã có bản mã hoá của tập và POST /playback có thể cấp vé cho tập đó. Hãy làm mờ hoặc ẩn các tập có giá trị false, thay vì để người xem chạm vào rồi gặp lỗi.

Cờ này là ảnh chụp tại lúc bạn tải catalog. POST /playback kiểm tra lại giấy phép và tập mỗi lần, và câu trả lời của nó mới là câu trả lời có giá trị. Nhận not_ready cho một tập từng có stream_ready: true là bình thường, ví dụ sau khi một phim bị rút.

Facet thể loại#

Mỗi phim mang ba facet tuỳ chọn cho màn hình duyệt và bộ lọc. null nghĩa là phim chưa được phân loại; hãy hiển thị phim mà không có facet đó thay vì đoán.

Phim còn có genres, một mảng nhãn thể loại dạng văn bản tự do, và language.

Văn bản và ảnh#

• synopsis_short dùng cho thẻ, synopsis_full dùng cho trang chi tiết. Độ dài khác nhau giữa các phim, nên hãy giới hạn (clamp) văn bản trong UI. synopsis_full có thể là null.
• episodes[].synopsis có thể là null. Khi đó đừng hiển thị gì.
• poster_url (phim) và poster_uri (tập) có thể là null trong lúc ảnh đang được chuẩn bị. Hãy hiển thị ảnh placeholder.

Giữ bản sao luôn mới#

Cache catalog trên server và làm mới theo lịch, thay vì gọi API mỗi lần mở app. Giấy phép hết hạn hoặc phim bị rút sẽ biến mất khỏi response kế tiếp; hãy gỡ mọi thứ không còn được liệt kê.

Catalog có bộ đếm rate limit riêng, tách khỏi playback và creatives. Xem Rate limit.