Livedeck widget SDK: funkcje i zdarzenia
Wszystko, co robi obiekt livedeck: zdarzenia, ustawienia, obrazy, dźwięki i kontekst.
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.
<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"
| Wywołanie | Co robi |
|---|---|
| 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
| Typ | Uprawnienie | Pola |
|---|---|---|
| gift | events.gift | user, gift { id, name, image, diamonds }, count, totalDiamonds, combo { count, ended }, toGuest |
| chat | events.chat | user (plus isModerator, isSubscriber, fanLevel), text |
| like | events.like | user (lub 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 lub checking |
| settings | brak | nowe ustawienia |
| context | brak | nowy kontekst, np. nowy rozmiar |
| ready | brak | raz po połączeniu |
| * | brak | 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.
{
"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.
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
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?