Livedeck widget SDK: функции и события
Всё, что умеет объект livedeck: события, настройки, картинки, звуки и контекст.
SDK — это небольшая библиотека, которую Livedeck отдаёт по адресу каждого виджета в /sdk/v1.js. Она связывает ваш виджет с оверлеем и предоставляет объект livedeck.
<script src="/sdk/v1.js"></script>Подключайте её перед своим кодом. Как только страница загрузится, SDK сам сообщит о себе оверлею. Ничего вызывать для этого не нужно.
Функции
livedeck.on(type, fn)
Вызывает fn для каждого события этого типа. Возвращает функцию, которая снова удаляет fn.
livedeck.off(type, fn)
Удаляет fn.
livedeck.ready(fn)
Вызывает fn, как только оверлей подключён и настройки получены. Также возвращает Promise.
livedeck.settings
Текущие настройки (только чтение). Когда пользователь что-то меняет, приходит событие settings.
livedeck.context
{ mode, format, locale, size, scale, test }. size — размер страницы в CSS-пикселях, scale — масштаб виджета с изменённым размером (1 по умолчанию). mode: live (ссылка для OBS), editor (предпросмотр) или demo (Marketplace).
livedeck.host
{ handle, nickname, avatar } стримера, только с разрешением host.profile, иначе null.
livedeck.image(ref)
Превращает ссылку на картинку (avatar, gift.image) в локальный адрес картинки. Promise с адресом или null.
livedeck.media.play(key, { volume })
Воспроизводит звук из медиа-настройки key через Livedeck с общей громкостью. volume от 0 до 1. Нужно разрешение media.play. Promise с true или false.
livedeck.media.url(key)
Локальный адрес картинки или клипа из медиа-настройки key. Promise с адресом или null.
livedeck.version
"1"
| Вызов | Что делает |
|---|---|
| livedeck.on(type, fn) | Вызывает fn для каждого события этого типа. Возвращает функцию, которая снова удаляет fn. |
| livedeck.off(type, fn) | Удаляет fn. |
| livedeck.ready(fn) | Вызывает fn, как только оверлей подключён и настройки получены. Также возвращает Promise. |
| livedeck.settings | Текущие настройки (только чтение). Когда пользователь что-то меняет, приходит событие settings. |
| livedeck.context | { mode, format, locale, size, scale, test }. size — размер страницы в CSS-пикселях, scale — масштаб виджета с изменённым размером (1 по умолчанию). mode: live (ссылка для OBS), editor (предпросмотр) или demo (Marketplace). |
| livedeck.host | { handle, nickname, avatar } стримера, только с разрешением host.profile, иначе null. |
| livedeck.image(ref) | Превращает ссылку на картинку (avatar, gift.image) в локальный адрес картинки. Promise с адресом или null. |
| livedeck.media.play(key, { volume }) | Воспроизводит звук из медиа-настройки key через Livedeck с общей громкостью. volume от 0 до 1. Нужно разрешение media.play. Promise с true или false. |
| livedeck.media.url(key) | Локальный адрес картинки или клипа из медиа-настройки key. Promise с адресом или null. |
| 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
Разрешение: нет
Поля: один раз после подключения
*
Разрешение: нет
Поля: все live-события выше
| Тип | Разрешение | Поля |
|---|---|---|
| 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 | нет | один раз после подключения |
| * | нет | все live-события выше |
У каждого live-события есть type и id. user — это { handle, nickname, avatar }: handle — имя пользователя TikTok без @, avatar — ссылка на картинку для livedeck.image(). Показывайте зрителей по имени пользователя ("@" + handle). nickname — отображаемое имя, которое ввёл зритель, и часто это настоящее имя: не показывайте его. Виджет никогда не получает числовые ID TikTok, адреса e-mail или ссылки.
{
"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 — сколько подарков уже отправлено, combo.ended — когда TikTok завершает серию. Никогда не суммируйте combo.count и не умножайте на него.
- Стоимость в монетах всегда берётся из события. Не используйте свой прайс-лист и не угадывайте цену по названию подарка.
- Самый крупный подарок: сравнивайте gift.diamonds. Топ донатеров / рейтинг: суммируйте totalDiamonds по user.handle.
- toGuest равен true, если подарок отправлен гостю в LIVE с несколькими гостями.
- Для конкретного подарка используйте настройку типа gift и сравнивайте e.gift.id с её значением.
Лайки
Во время LIVE Livedeck объединяет лайки каждые 500 мс в одно событие: 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.
- У виджета нет хранилища браузера: localStorage, sessionStorage, IndexedDB и cookies заблокированы. Храните состояние в памяти. Когда пользователь перезагружает оверлей, виджет начинает заново.
- Загружать можно только из своего пакета. fetch на другие сайты, WebSockets, фреймы, формы, всплывающие окна и переходы на другие страницы заблокированы.
- Оверлей каждые 2000 мс проверяет, отвечает ли ваш виджет. SDK отвечает сам, пока ваш код не блокирует браузер.
- Во время LIVE виджет получает не более 50 сообщений в секунду. При очень большом количестве событий в приоритете подарки и чат.
- Виджет может отправлять оверлею не более 10 запросов в секунду (например, livedeck.image), каждый не более 64 КБ. SDK запоминает картинки, так что одна и та же ссылка учитывается только один раз.
- Звуки, воспроизводимые через livedeck.media.play, идут через аудио Livedeck, поэтому действуют общая громкость и выбранный пользователем выход. Можно также воспроизводить звуки из пакета через <audio>, но они обходят громкость Livedeck.
- Кладите шрифты в пакет в формате .woff2 и подключайте через @font-face по относительному пути. Картинки можно генерировать и самостоятельно (canvas, data:, blob:).
Статья была полезной?