Livedeck widget SDK:函数和事件
livedeck 对象的全部功能:事件、设置、图片、声音和上下文。
SDK 是一个小型库,Livedeck 会在每个 widget 地址下的 /sdk/v1.js 提供它。它负责把你的 widget 连接到 overlay,并提供 livedeck 对象。
<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"
| 调用 | 作用 |
|---|---|
| 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
权限: 无
字段: 连接后触发一次
*
权限: 无
字段: 以上所有直播事件
| 类型 | 权限 | 字段 |
|---|---|---|
| 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、邮箱地址或链接。
{
"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 元素。
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);示例:带头像的聊天
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:)。
这篇文章对你有帮助吗?