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