Livedeck widget SDK: hàm và sự kiện

Mọi thứ đối tượng livedeck làm được: sự kiện, cài đặt, hình ảnh, âm thanh và ngữ cảnh.

9 phút đọc Cập nhật 4 thg 11, 2026

SDK là một thư viện nhỏ mà Livedeck cung cấp tại địa chỉ của mỗi widget, dưới đường dẫn /sdk/v1.js. Nó kết nối widget của bạn với overlay và cung cấp đối tượng livedeck.

html
<script src="/sdk/v1.js"></script>

Hãy tải nó trước code của bạn. Ngay khi trang tải xong, SDK sẽ tự động báo cho overlay. Bạn không cần gọi gì cả.

Hàm

livedeck.on(type, fn)

Gọi fn cho mỗi sự kiện thuộc loại này. Trả về một hàm để gỡ bỏ fn.

livedeck.off(type, fn)

Gỡ bỏ fn.

livedeck.ready(fn)

Gọi fn khi overlay đã kết nối và đã có cài đặt. Đồng thời trả về một Promise.

livedeck.settings

Cài đặt hiện tại (chỉ đọc). Khi người dùng thay đổi gì đó, sự kiện settings sẽ được gửi đến.

livedeck.context

{ mode, format, locale, size, scale, test }. size là kích thước trang tính bằng pixel CSS, scale là mức thu phóng của widget đã đổi kích thước (mặc định là 1). mode là live (link OBS), editor (xem trước) hoặc demo (Marketplace).

livedeck.host

{ handle, nickname, avatar } của streamer, chỉ khi có quyền host.profile, nếu không thì là null.

livedeck.image(ref)

Chuyển một tham chiếu hình ảnh (avatar, gift.image) thành địa chỉ hình ảnh cục bộ. Promise trả về địa chỉ hoặc null.

livedeck.media.play(key, { volume })

Phát âm thanh từ cài đặt media key qua Livedeck, theo âm lượng tổng. volume từ 0 đến 1. Cần quyền media.play. Promise trả về true hoặc false.

livedeck.media.url(key)

Địa chỉ cục bộ của hình ảnh hoặc clip từ cài đặt media key. Promise trả về địa chỉ hoặc null.

livedeck.version

"1"

Sự kiện

gift

Quyền: events.gift

Các trường: user, gift { id, name, image, diamonds }, count, totalDiamonds, combo { count, ended }, toGuest

chat

Quyền: events.chat

Các trường: user (kèm isModerator, isSubscriber, fanLevel), text

like

Quyền: events.like

Các trường: user (hoặc null), count, total

follow

Quyền: events.follow

Các trường: user

share

Quyền: events.share

Các trường: user

join

Quyền: events.join

Các trường: user

fanclub

Quyền: events.fanclub

Các trường: user

viewers

Quyền: events.viewers

Các trường: count

stream

Quyền: stream.status

Các trường: status: live, offline hoặc checking

settings

Quyền: không có

Các trường: cài đặt mới

context

Quyền: không có

Các trường: ngữ cảnh mới, ví dụ kích thước mới

ready

Quyền: không có

Các trường: một lần sau khi kết nối

*

Quyền: không có

Các trường: mọi sự kiện live ở trên

Mỗi sự kiện live đều có type và id. user là { handle, nickname, avatar }: handle là tên người dùng TikTok không có @, avatar là tham chiếu hình ảnh dùng cho livedeck.image(). Hãy hiển thị người xem bằng tên người dùng ("@" + handle). nickname là tên hiển thị do người xem tự nhập và thường là tên thật: đừng hiển thị nó. Widget không bao giờ nhận được ID số TikTok, địa chỉ e-mail hay link.

json
{
  "type": "gift",
  "id": "42",
  "user": { "handle": "lena.loops", "nickname": "Lena", "avatar": "i:7" },
  "gift": { "id": 5655, "name": "Rose", "image": "i:8", "diamonds": 1 },
  "count": 3,
  "totalDiamonds": 3,
  "combo": { "count": 7, "ended": false },
  "toGuest": false
}

Quà tặng

  • gift.diamonds là giá xu của MỘT món quà. count là số quà mới trong sự kiện này, totalDiamonds = count × gift.diamonds là số xu được cộng thêm. Combo đã được tính sẵn: chỉ cần cộng dồn count và totalDiamonds, không cần gì khác.
  • combo là cả chuỗi quà, chỉ dùng để hiển thị ("Rose ×7"): combo.count là số quà tính đến hiện tại, combo.ended khi TikTok kết thúc chuỗi. Không bao giờ cộng dồn combo.count và không bao giờ nhân với nó.
  • Giá trị xu luôn lấy từ sự kiện. Không dùng bảng giá riêng hay đoán giá từ tên quà.
  • Món quà lớn nhất: so sánh gift.diamonds. Người ủng hộ hàng đầu / bảng xếp hạng: cộng dồn totalDiamonds theo user.handle.
  • toGuest là true khi quà được tặng cho khách mời trong LIVE nhiều khách.
  • Với một món quà cụ thể, hãy dùng setting kiểu gift và so sánh e.gift.id với giá trị của nó.

Lượt thích

Trong LIVE, Livedeck gom lượt thích mỗi 500 ms thành một sự kiện: count là tổng trong khoảng đó, total là tổng của cả LIVE.

Ví dụ: mục tiêu quà

Khớp với manifest.json trên trang "Tham chiếu manifest.json". Trang cần có phần tử #bar và #label.

js
let total = 0;
let reached = false;

function render() {
  const goal = Number(livedeck.settings.goal) || 100;
  const bar = document.getElementById("bar");
  bar.style.width = Math.min(total / goal, 1) * 100 + "%";
  bar.style.background = livedeck.settings.accent;
  document.getElementById("label").textContent = total + " / " + goal;
  if (!reached && total >= goal) {
    reached = true;
    if (livedeck.settings.doneSound) livedeck.media.play("doneSound", { volume: 0.8 });
  }
}

livedeck.on("gift", (e) => {
  const only = livedeck.settings.giftId;
  if (only && e.gift.id !== only) return;
  total += e.count; // counts gifts; for a diamond goal use e.totalDiamonds
  render();
});

livedeck.on("settings", render);
livedeck.ready(render);

Ví dụ: chat kèm ảnh đại diện

js
livedeck.on("chat", async (e) => {
  const row = document.createElement("div");
  const img = document.createElement("img");
  img.alt = "";
  row.append(img, "@" + e.user.handle + ": " + e.text);
  document.getElementById("chat").prepend(row);
  // picture reference → local address (or null, then it stays empty)
  const url = await livedeck.image(e.user.avatar);
  if (url) img.src = url;
});

Lưu ý

  • Tên và nội dung chat do người xem viết. Luôn chèn chúng bằng textContent, không bao giờ dùng innerHTML.
  • Widget không có bộ nhớ trình duyệt: localStorage, sessionStorage, IndexedDB và cookie đều bị chặn. Hãy giữ trạng thái trong bộ nhớ. Khi người dùng tải lại overlay, widget sẽ bắt đầu lại từ đầu.
  • Chỉ có thể tải từ gói của chính bạn. fetch tới trang khác, WebSocket, frame, form, pop-up và chuyển trang đều bị chặn.
  • Overlay kiểm tra mỗi 2000 ms xem widget còn phản hồi không. SDK tự trả lời miễn là code của bạn không làm treo trình duyệt.
  • Trong LIVE, mỗi widget nhận tối đa 50 tin nhắn mỗi giây. Khi có quá nhiều sự kiện, quà và chat được ưu tiên.
  • Widget của bạn được gửi tối đa 10 yêu cầu mỗi giây tới overlay (ví dụ livedeck.image), mỗi yêu cầu tối đa 64 KB. SDK ghi nhớ ảnh, nên cùng một tham chiếu chỉ tính một lần.
  • Âm thanh phát bằng livedeck.media.play đi qua hệ thống âm thanh của Livedeck, nên áp dụng âm lượng tổng và đầu ra người dùng đã chọn. Bạn cũng có thể phát âm thanh từ gói bằng <audio>, nhưng chúng sẽ bỏ qua âm lượng của Livedeck.
  • Đưa font vào gói dưới dạng .woff2 và tải bằng @font-face với đường dẫn tương đối. Bạn cũng có thể tự tạo ảnh (canvas, data:, blob:).

Bài viết này có hữu ích không?