Livedeck widget SDK: funkcje i zdarzenia

Wszystko, co robi obiekt livedeck: zdarzenia, ustawienia, obrazy, dźwięki i kontekst.

9 min czytania Zaktualizowano 4 lis 2026

SDK to mała biblioteka, którą Livedeck udostępnia pod adresem każdego widgetu w /sdk/v1.js. Łączy twój widget z overlayem i udostępnia obiekt livedeck.

html
<script src="/sdk/v1.js"></script>

Załaduj ją przed własnym kodem. Gdy tylko strona się załaduje, SDK samo zgłasza się do overlayu. Nie musisz nic w tym celu wywoływać.

Funkcje

livedeck.on(type, fn)

Wywołuje fn dla każdego zdarzenia tego typu. Zwraca funkcję, która z powrotem usuwa fn.

livedeck.off(type, fn)

Usuwa fn.

livedeck.ready(fn)

Wywołuje fn, gdy overlay jest połączony, a ustawienia są już dostępne. Zwraca też Promise.

livedeck.settings

Aktualne ustawienia (tylko do odczytu). Gdy użytkownik coś zmieni, przychodzi zdarzenie settings.

livedeck.context

{ mode, format, locale, size, scale, test }. size to rozmiar strony w pikselach CSS, scale to powiększenie przeskalowanego widgetu (domyślnie 1). mode to live (link OBS), editor (podgląd) lub demo (Marketplace).

livedeck.host

{ handle, nickname, avatar } streamera, tylko z uprawnieniem host.profile, w przeciwnym razie null.

livedeck.image(ref)

Zamienia odwołanie do obrazu (avatar, gift.image) na lokalny adres obrazu. Promise z adresem lub null.

livedeck.media.play(key, { volume })

Odtwarza dźwięk z ustawienia multimediów key przez Livedeck, z głośnością główną. volume od 0 do 1. Wymaga media.play. Promise z true lub false.

livedeck.media.url(key)

Lokalny adres obrazu lub klipu z ustawienia multimediów key. Promise z adresem lub null.

livedeck.version

"1"

Zdarzenia

gift

Uprawnienie: events.gift

Pola: user, gift { id, name, image, diamonds }, count, totalDiamonds, combo { count, ended }, toGuest

chat

Uprawnienie: events.chat

Pola: user (plus isModerator, isSubscriber, fanLevel), text

like

Uprawnienie: events.like

Pola: user (lub null), count, total

follow

Uprawnienie: events.follow

Pola: user

share

Uprawnienie: events.share

Pola: user

join

Uprawnienie: events.join

Pola: user

fanclub

Uprawnienie: events.fanclub

Pola: user

viewers

Uprawnienie: events.viewers

Pola: count

stream

Uprawnienie: stream.status

Pola: status: live, offline lub checking

settings

Uprawnienie: brak

Pola: nowe ustawienia

context

Uprawnienie: brak

Pola: nowy kontekst, np. nowy rozmiar

ready

Uprawnienie: brak

Pola: raz po połączeniu

*

Uprawnienie: brak

Pola: każde zdarzenie LIVE powyżej

Każde zdarzenie LIVE ma type i id. user to { handle, nickname, avatar }: handle to nazwa użytkownika TikTok bez @, avatar to odwołanie do obrazu dla livedeck.image(). Pokazuj widzów po nazwie użytkownika („@” + handle). nickname to nazwa wyświetlana wpisana przez widza i często jest to prawdziwe imię i nazwisko: nie pokazuj jej. Widget nigdy nie dostaje numerycznych ID TikTok, adresów e-mail ani linków.

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
}

Prezenty

  • gift.diamonds to cena JEDNEGO prezentu w monetach. count to liczba nowych prezentów w tym zdarzeniu, a totalDiamonds = count × gift.diamonds to monety, które dodaje. Comba są już rozliczone: sumuj count i totalDiamonds, nic więcej.
  • combo to cała seria, tylko do wyświetlania („Rose ×7”): combo.count to liczba prezentów do tej pory, combo.ended pojawia się, gdy TikTok ją zamknie. Nigdy nie sumuj combo.count i nigdy przez nie nie mnóż.
  • Wartości monet zawsze pochodzą ze zdarzenia. Nigdy nie używaj własnego cennika ani nie zgaduj ceny po nazwie prezentu.
  • Największy pojedynczy prezent: porównuj gift.diamonds. Top wspierający / ranking: sumuj totalDiamonds dla każdego user.handle.
  • toGuest ma wartość true, gdy prezent trafił do gościa w LIVE z wieloma gośćmi.
  • Dla jednego konkretnego prezentu użyj ustawienia typu gift i porównaj e.gift.id z jego wartością.

Lajki

W trakcie LIVE Livedeck co 500 ms łączy polubienia w jedno zdarzenie: count to suma w tym czasie, total to łączna liczba w całym LIVE.

Przykład: cel prezentów

Pasuje do manifest.json ze strony „manifest.json reference”. Strona potrzebuje elementów #bar i #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);

Przykład: czat ze zdjęciami profilowymi

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;
});

Warto wiedzieć

  • Nazwy i teksty czatu piszą widzowie. Zawsze wstawiaj je przez textContent, nigdy przez innerHTML.
  • Widget nie ma pamięci przeglądarki: localStorage, sessionStorage, IndexedDB i cookies są zablokowane. Trzymaj stan w pamięci. Gdy użytkownik przeładuje overlay, widget startuje od nowa.
  • Wczytywać można tylko z własnej paczki. fetch do innych stron, WebSockets, ramki, formularze, pop-upy i przechodzenie na inne strony są zablokowane.
  • Overlay co 2000 ms sprawdza, czy widget nadal odpowiada. SDK odpowiada sam, dopóki twój kod nie blokuje przeglądarki.
  • W trakcie LIVE widget dostaje maksymalnie 50 wiadomości na sekundę. Przy bardzo dużej liczbie zdarzeń pierwszeństwo mają prezenty i czat.
  • Widget może wysłać do overlayu maksymalnie 10 żądań na sekundę (np. livedeck.image), każde maksymalnie 64 KB. SDK zapamiętuje obrazy, więc to samo odwołanie kosztuje tylko raz.
  • Dźwięki odtwarzane przez livedeck.media.play idą przez audio Livedeck, więc obowiązuje główna głośność i wyjście wybrane przez użytkownika. Możesz też odtwarzać dźwięki z paczki przez <audio>, ale wtedy omijają one głośność Livedeck.
  • Dodaj czcionki do paczki jako .woff2 i wczytaj je przez @font-face ze ścieżką względną. Możesz też samodzielnie generować obrazy (canvas, data:, blob:).

Czy ten artykuł był pomocny?