SDK віджетів Livedeck: функції та події

Усе, що вміє об’єкт 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 KB. SDK запам’ятовує зображення, тож те саме посилання коштує лише раз.
  • Звуки, відтворені через livedeck.media.play, проходять через аудіо Livedeck, тому діють загальна гучність і вибраний користувачем вихід. Також можна відтворювати звуки з пакета через <audio>, але вони обходять гучність Livedeck.
  • Додавайте шрифти в пакет у форматі .woff2 і підключайте через @font-face з відносним шляхом. Зображення можна також генерувати самостійно (canvas, data:, blob:).

Ця стаття була корисною?