Livedeck widget SDK:函数和事件

livedeck 对象的全部功能:事件、设置、图片、声音和上下文。

阅读约 9 分钟 更新于 2026年11月4日

SDK 是一个小型库,Livedeck 会在每个 widget 地址下的 /sdk/v1.js 提供它。它负责把你的 widget 连接到 overlay,并提供 livedeck 对象。

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

请在你自己的代码之前加载它。页面加载完成后,SDK 会自动向 overlay 报到,你无需调用任何东西。

函数

livedeck.on(type, fn)

对该类型的每个事件调用 fn。返回一个可再次移除 fn 的函数。

livedeck.off(type, fn)

移除 fn。

livedeck.ready(fn)

在 overlay 连接完成且设置已就绪后调用 fn。同时返回一个 Promise。

livedeck.settings

当前设置(只读)。用户修改设置时,会收到 settings 事件。

livedeck.context

{ mode, format, locale, size, scale, test }。size 是以 CSS 像素计的页面尺寸,scale 是缩放后 widget 的缩放比例(默认为 1)。mode 为 live(OBS 链接)、editor(预览)或 demo(Marketplace)。

livedeck.host

主播的 { handle, nickname, avatar },仅在拥有 host.profile 权限时提供,否则为 null。

livedeck.image(ref)

将图片引用(avatar、gift.image)转换为本地图片地址。返回包含地址或 null 的 Promise。

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

通过 Livedeck 以主音量播放媒体设置 key 中的声音。volume 取值 0 到 1。需要 media.play 权限。返回包含 true 或 false 的 Promise。

livedeck.media.url(key)

媒体设置 key 中图片或视频片段的本地地址。返回包含地址或 null 的 Promise。

livedeck.version

"1"

事件

gift

权限: events.gift

字段: user, gift { id, name, image, diamonds }, count, totalDiamonds, combo { count, ended }, toGuest

chat

权限: events.chat

字段: user(另含 isModerator、isSubscriber、fanLevel), text

like

权限: events.like

字段: user(或 null), count, total

follow

权限: events.follow

字段: user

share

权限: events.share

字段: user

join

权限: events.join

字段: user

fanclub

权限: events.fanclub

字段: user

viewers

权限: events.viewers

字段: count

stream

权限: stream.status

字段: status:live、offline 或 checking

settings

权限: 无

字段: 新的设置

context

权限: 无

字段: 新的上下文,例如新的尺寸

ready

权限: 无

字段: 连接后触发一次

*

权限: 无

字段: 以上所有直播事件

每个直播事件都有 type 和 id。user 为 { handle, nickname, avatar }:handle 是不带 @ 的 TikTok 用户名,avatar 是供 livedeck.image() 使用的图片引用。请用用户名("@" + handle)显示观众。nickname 是观众自己填写的昵称,常常是真实姓名:不要显示它。widget 永远不会获得 TikTok 数字 ID、邮箱地址或链接。

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
}

礼物

  • gift.diamonds 是单个礼物的金币价格。count 是本次事件中新增的礼物数量,totalDiamonds = count × gift.diamonds,即本次增加的金币数。连击已自动折算:只需累加 count 和 totalDiamonds,无需其他处理。
  • combo 是整个连击,仅用于显示(“Rose ×7”):combo.count 是目前为止的礼物数,TikTok 结束连击后 combo.ended 为真。切勿累加 combo.count,也切勿用它做乘法。
  • 金币数值始终来自事件本身。切勿使用自己的价格表,也不要根据礼物名称猜测价格。
  • 最大单个礼物:比较 gift.diamonds。最佳支持者/排行榜:按 user.handle 累加 totalDiamonds。
  • 当礼物送给多人连线 LIVE 中的嘉宾时,toGuest 为 true。
  • 如需针对某个特定礼物,请使用 gift 类型的设置,并将 e.gift.id 与其值进行比较。

点赞

LIVE 期间,Livedeck 每 500 ms 将点赞合并为一个事件:count 是这段时间内的总数,total 是本场 LIVE 的累计点赞数。

示例:礼物目标

与“manifest.json 参考”页面中的 manifest.json 对应。页面需要一个 #bar 和一个 #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);

示例:带头像的聊天

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;
});

小贴士

  • 名称和聊天内容由观众输入。请始终用 textContent 插入,切勿使用 innerHTML。
  • widget 没有浏览器存储:localStorage、sessionStorage、IndexedDB 和 cookie 均被禁用。请将状态保存在内存中。用户重新加载 overlay 时,widget 会从头开始。
  • 只能从你自己的包中加载内容。对其他网站的 fetch、WebSocket、框架、表单、弹窗以及页面跳转均被禁止。
  • overlay 每 2000 ms 检查一次 widget 是否仍有响应。只要你的代码不阻塞浏览器,SDK 会自动应答。
  • LIVE 期间,每个 widget 每秒最多接收 50 条消息。事件很多时,礼物和聊天优先。
  • 你的 widget 每秒最多向 overlay 发送 10 个请求(例如 livedeck.image),每个最大 64 KB。SDK 会缓存图片,因此同一引用只计一次。
  • 通过 livedeck.media.play 播放的声音会经过 Livedeck 的音频系统,因此主音量和用户选择的输出设备都会生效。你也可以用 <audio> 播放包内的声音,但这样会绕过 Livedeck 的音量控制。
  • 请将字体以 .woff2 格式放入包中,并通过 @font-face 和相对路径加载。你也可以自行生成图片(canvas、data:、blob:)。

这篇文章对你有帮助吗?