Bỏ qua, tới nội dung chính
LiveBridgeLiveBridge

Tham chiếu SDK

Các handler của LiveBridgeGame, hình dạng sự kiện, quyền riêng tư của người xem, điều cấm và CSP của sandbox.

SDK LiveBridge

Nạp bằng đúng dòng này (trước script của game). Đừng copy hay bundle SDK: serve tự đổi URL này sang bản chạy cục bộ, còn khi chạy thật nó là bản của LiveBridge.

<script src="https://livebridge.vn/sdk/livebridge.js"></script>
<script>
  const game = new LiveBridgeGame({
    onAction(actionId, event, rule) { /* quà đã được streamer ánh xạ tới hành động của bạn */ },
    onGift(event) { /* MỌI quà, kể cả quà chưa ánh xạ */ },
    onChat(comment, user, event) {},
    onFollow(user, event) {},
    onShare(user, event) {},
    onMember(user, event) {},   // người vào phòng
    onLike(user, event) {},     // event.like.count = số like của lô này
  });
</script>

Tất cả handler (đều tuỳ chọn):

  • onReady(config, actionMap): SDK đã đọc xong manifest và bản ánh xạ quà. config là manifest.json của bạn. `actionMap` có thể là `null` nếu lần đọc đầu thất bại (lỗi mạng, 429): khi đó bản ánh xạ đến sau qua onConfig. Đừng giả định actionMap luôn có.
  • onConfig(actionMap): streamer vừa lưu lại ánh xạ quà (không cần tải lại trang), hoặc bản ánh xạ đến muộn sau onReady.
  • onAction(actionId, event, rule): một quà khớp một quy tắc. rule có actionId, amount (mặc định 1), và giftName hoặc minDiamonds/maxDiamonds.
  • onGift(event): mọi quà. Luôn gọi, kể cả khi onAction cũng gọi.
  • onChat(comment, user, event), onFollow(user, event), onShare(user, event), onMember(user, event), onLike(user, event).
  • onEvent(event): mọi sự kiện thô (cả gift, chat...).
  • onConnect(), onDisconnect(): socket mở / đóng. SDK tự kết nối lại sau vài giây, trừ khi link bị thu hồi.
  • onTikTokStatus("connected" | "connecting" | "ended" | "disconnected"): tình trạng phòng TikTok của streamer. Socket có thể mở trong khi streamer chưa bấm kết nối TikTok.
  • apiOrigin (tuỳ chọn): chỉ cần khi bạn tự host SDK. Đừng dùng.
  • Hàm tiện ích: LiveBridgeGame.resolveGiftAction(actionMap, event), LiveBridgeGame.getDiamonds(event) (= diamondCount x repeatCount), LiveBridgeGame.getUser(event); game.destroy() để dừng.

Hình dạng sự kiện (sau khi lọc quyền riêng tư; trường có thể thiếu thì kiểm tra trước khi dùng):

{ type: "gift", seq, ts, channel,
  user: { id, uniqueId, nickname, avatar, roles?: { moderator, subscriber, follower, member } },
  gift: { id, name, diamondCount, repeatCount, icon? } }          // chat: chat: { comment }
                                                                   // like: like: { count, total? }

gift.icon luôn là "" với game của nhà phát triển (CSP chặn ảnh quà từ CDN TikTok và LiveBridge chưa có proxy cho ảnh quà): tự vẽ biểu tượng quà trong game nếu cần.

Quy tắc ánh xạ quà: tên quà khớp chính xác > khoảng kim cương (diamondCount x repeatCount nằm trong minDiamonds..maxDiamonds) > hành động có actionId là "default". Streamer có thể đổi ánh xạ bất kỳ lúc nào, nên luôn xử lý cả onGift cho quà chưa ánh xạ.

Quyền riêng tư (streamer chọn cho từng game). Mặc định gửi tên và avatar. Khi streamer tắt tên: user.id thành anon-<16 hex>, user.uniqueId thành viewer-<4 hex>, user.nickname thành Viewer #<4 hex>; mỗi người xem luôn nhận cùng một mã trong cùng phòng và game. user.avatar là URL ảnh qua proxy của LiveBridge (https://livebridge.vn/api/avatar?u=<uniqueId>&s=96, CSP cho phép; chưa có ảnh thì proxy trả ảnh mặc định), không bao giờ là URL CDN TikTok. Khi tắt avatar, và cả khi tắt tên (URL proxy chứa tên thật): user.avatar là "". Game phải hiển thị tốt cả hai trường hợp (ví dụ chữ cái đầu thay avatar).

Chế độ token. Game chỉ có ?t=. Không có ?t= thì SDK ở chế độ demo (không kết nối, không lỗi). Link bị thu hồi (streamer bấm "Ngắt game này", đổi tài khoản TikTok, quản trị gỡ game) thì socket đóng với mã 4003: SDK dừng hẳn và gọi onDisconnect; hãy hiện "Link hết hạn, hãy mở lại game từ LiveBridge". window.__LIVEBRIDGE__.status là idle, open, closed hoặc revoked.

Phải tạo `new LiveBridgeGame({...})` ngay khi trang tải, không chờ người dùng bấm. Bộ kiểm tra tự động mở game trong trình duyệt thật và chờ trạng thái open.

Điều cấm

  • Không gọi mạng ra ngoài connectOrigins (fetch, XHR, WebSocket, ảnh, font ngoài danh sách cho phép ở mục CSP). Cần API riêng thì khai báo origin đó trong connectOrigins.
  • Không lưu hay gửi dữ liệu người xem đi nơi nào khác: tên, avatar, id, bình luận chỉ dùng để hiển thị trong game, không ghi vào localStorage/cookie/IndexedDB/máy chủ riêng, không đưa vào URL.
  • Không hỏi, đọc hay dùng `?key=` hay mã kết nối (room key) của streamer. Game chỉ nhận ?t=.
  • Không giả định bàn phím hay chuột: game được dùng khi streamer livestream, người điều khiển là người xem qua quà và chat.
  • Không dùng dịch vụ phân tích bên ngoài (Google Analytics, Sentry, Mixpanel...) và không nhúng iframe hay script quảng cáo.
  • Dữ liệu người xem là không tin cậy: hiển thị bằng textContent, không bao giờ innerHTML, eval hay document.write với dữ liệu đó.
  • Không có nội dung vi phạm pháp luật, khiêu dâm, bạo lực cực đoan, thù ghét, hay cờ bạc ăn tiền thật. LiveBridge có quyền gỡ game bất cứ lúc nào (xem điều khoản nhà phát triển).
  • Dùng đường dẫn tương đối (game.js, ./img/a.png), không bắt đầu bằng /: game chạy dưới https://<id-game>.<miền sandbox>/v/<version>/.

CSP (chính sách nội dung của sandbox)

Mọi file của game được trả với CSP này; serve áp dụng đúng như vậy để bạn thấy lỗi sớm:

  • default-src 'self'.
  • Script: file của game, /sdk/ của LiveBridge, inline script, WebAssembly ('wasm-unsafe-eval'), và các CDN https://cdnjs.cloudflare.com, https://cdn.jsdelivr.net, https://unpkg.com.
  • Gọi mạng (fetch, XHR, WebSocket): chính game, API LiveBridge, và connectOrigins.
  • Ảnh, âm thanh, video, font: file của game, data:, blob:, API LiveBridge, ba CDN trên và connectOrigins (https). Google Fonts được phép (CSS từ fonts.googleapis.com, font từ fonts.gstatic.com).
  • Web Worker: file của game hoặc blob:. Không có <object>, <base>, <form action>.
  • Game được nhúng trong OBS và dashboard (không có frame-ancestors), nhưng không nhúng trang ngoài.