Livedeck widget SDK: функции и события

Всё, что умеет объект livedeck: события, настройки, картинки, звуки и контекст.

9 мин чтения Обновлено 4 нояб. 2026 г.

SDK — это небольшая библиотека, которую Livedeck отдаёт по адресу каждого виджета в /sdk/v1.js. Она связывает ваш виджет с оверлеем и предоставляет объект livedeck.

html
<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"

События

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 или ссылки.

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 — сколько подарков уже отправлено, 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.

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.
  • У виджета нет хранилища браузера: 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:).

Статья была полезной?