Creative

Feed creative cung cấp cho hệ thống marketing của bạn một bản ghi dữ liệu lâu dài cho mỗi ad creative mà tổ chức của bạn đã duyệt trên Wandura. Mỗi bản ghi cho biết creative là gì: phim, các tập và cảnh được dùng, định dạng và thời lượng, hook, formula dùng để dựng, và thời điểm quyền sử dụng phim của bạn kết thúc. Hệ thống của bạn lưu các bản ghi này và tự quyết định dùng creative nào, dùng thế nào.

Feed chứa gì#

Feed trả về các creative thuộc tổ chức của bạn có status approved hoặc pushed (đã giao). Creative ở status khác, ví dụ bản nháp, không được đưa vào. Creative của tổ chức khác không bao giờ hiện ra.

Bản ghi không bao giờ chứa URL media. Feed mô tả creative; file video hoàn chỉnh không được giao qua API này. Hãy hỏi Wandura file hoàn chỉnh đến hệ thống của bạn bằng cách nào.

final.ready cho biết bản render hoàn chỉnh của creative đã có chưa.

Endpoint#

Cả hai đều cần key có scope creatives:export, bạn tự tạo được trên trang Developers của partner portal. Xem Xác thực.

Envelope của response#

Khác với endpoint catalog và playback, endpoint creatives bọc mọi response trong một envelope:

{
  "code": 0,
  "message": "ok",
  "data": { "items": [], "next_cursor": null },
  "server_time": 1790679032
}

code là 0 khi thành công và là mã lỗi bốn chữ số trong trường hợp khác. Timestamp trong feed này, kể cả server_time, tính bằng giây Unix epoch. Xem Lỗi.

Đồng bộ incremental#

Bản ghi được trả về theo thứ tự cập nhật cũ nhất trước, sắp theo updated_at rồi theo ID, nên cập nhật mới không bao giờ làm xê dịch các trang bạn đã đọc.

1. Lần đồng bộ đầu. Gọi GET /creatives?limit=100 không kèm updated_since. Chừng nào data.next_cursor chưa là null, gọi lại với cursor=<next_cursor>.
2. Lưu checkpoint. Giữ lại updated_at lớn nhất bạn nhận được.
3. Các lần đồng bộ sau. Gọi với updated_since=<checkpoint> và lại phân trang bằng cursor. Chỉ các bản ghi được cập nhật sau hẳn giây đó (>) được trả về.

curl -s "https://www.wandura.ai/api/delivery/v1/creatives?updated_since=1790600000&limit=100" \
  -H "Authorization: Bearer $WANDURA_API_KEY"

updated_at được làm tròn xuống theo giây, nên một bản ghi có thể xuất hiện lại ở lần đồng bộ sau. Hãy lưu bản ghi theo khoá creative_id và ghi đè khi trùng.

Coi giá trị cursor là opaque. Truyền lại đúng y như khi nhận.

Creative rời khỏi feed#

Feed không có sự kiện xoá. Nếu một creative không còn được duyệt, nó đơn giản là không xuất hiện nữa. Để xác nhận một creative đã lưu vẫn còn dùng được, gọi GET /creatives/{id}: endpoint trả 404 (code 4040) cho creative không còn trong feed.

Bản ghi#

Các trường chính của một bản ghi được liệt kê bên dưới. Danh sách đầy đủ, kèm kiểu dữ liệu, nằm trong tài liệu tham chiếu liệt kê creative.

rights.ends_at là 00:00 UTC của ngày cuối cùng trong quyền export phim. 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 ends_at + 86400.

Phiên bản#

Mỗi bản ghi mang schema_version, hiện là 1. Trường mới có thể được thêm vào mà không đổi giá trị này, nên hãy bỏ qua các trường bạn không nhận ra.

Rate limit#

Hai endpoint creatives dùng chung một bộ đếm rate limit, tách riêng khỏi catalog. Đồng bộ vài lần mỗi giờ vẫn còn cách xa ngưỡng này. Xem Rate limit.