Livedeck Widget SDK: Funktionen und Ereignisse
Alles, was das Objekt livedeck kann: Ereignisse, Einstellungen, Bilder, Töne und Kontext.
Das SDK ist eine kleine Bibliothek, die Livedeck an der Adresse jedes Widgets unter /sdk/v1.js ausliefert. Sie verbindet dein Widget mit dem Overlay und stellt das Objekt livedeck bereit.
<script src="/sdk/v1.js"></script>Binde es vor deinem eigenen Code ein. Sobald die Seite geladen ist, meldet sich das SDK selbst beim Overlay. Du musst dafür nichts aufrufen.
Funktionen
livedeck.on(typ, fn)
Ruft fn bei jedem Ereignis dieses Typs auf. Gibt eine Funktion zurück, die fn wieder abmeldet.
livedeck.off(typ, fn)
Meldet fn ab.
livedeck.ready(fn)
Ruft fn auf, sobald das Overlay verbunden ist und die Einstellungen da sind. Gibt auch ein Promise zurück.
livedeck.settings
Die aktuellen Einstellungen (nur lesen). Ändert der Nutzer etwas, kommt das Ereignis settings.
livedeck.context
{ mode, format, locale, size, scale, test }. size ist die Seitengröße in CSS-Pixeln, scale der Zoom des vergrößerten Widgets (1 bei default). mode ist live (OBS-Link), editor (Vorschau) oder demo (Marketplace).
livedeck.host
{ handle, nickname, avatar } des Streamers, nur mit dem Recht host.profile, sonst null.
livedeck.image(ref)
Macht aus einer Bild-Referenz (avatar, gift.image) eine lokale Bild-Adresse. Promise mit Adresse oder null.
livedeck.media.play(key, { volume })
Spielt den Ton aus der Medien-Einstellung key über Livedeck ab, mit der Master-Lautstärke. volume 0 bis 1. Braucht media.play. Promise mit true oder false.
livedeck.media.url(key)
Lokale Adresse für das Bild oder den Clip aus der Medien-Einstellung key. Promise mit Adresse oder null.
livedeck.version
"1"
| Aufruf | Was es tut |
|---|---|
| livedeck.on(typ, fn) | Ruft fn bei jedem Ereignis dieses Typs auf. Gibt eine Funktion zurück, die fn wieder abmeldet. |
| livedeck.off(typ, fn) | Meldet fn ab. |
| livedeck.ready(fn) | Ruft fn auf, sobald das Overlay verbunden ist und die Einstellungen da sind. Gibt auch ein Promise zurück. |
| livedeck.settings | Die aktuellen Einstellungen (nur lesen). Ändert der Nutzer etwas, kommt das Ereignis settings. |
| livedeck.context | { mode, format, locale, size, scale, test }. size ist die Seitengröße in CSS-Pixeln, scale der Zoom des vergrößerten Widgets (1 bei default). mode ist live (OBS-Link), editor (Vorschau) oder demo (Marketplace). |
| livedeck.host | { handle, nickname, avatar } des Streamers, nur mit dem Recht host.profile, sonst null. |
| livedeck.image(ref) | Macht aus einer Bild-Referenz (avatar, gift.image) eine lokale Bild-Adresse. Promise mit Adresse oder null. |
| livedeck.media.play(key, { volume }) | Spielt den Ton aus der Medien-Einstellung key über Livedeck ab, mit der Master-Lautstärke. volume 0 bis 1. Braucht media.play. Promise mit true oder false. |
| livedeck.media.url(key) | Lokale Adresse für das Bild oder den Clip aus der Medien-Einstellung key. Promise mit Adresse oder null. |
| livedeck.version | "1" |
Ereignisse
gift
Recht: events.gift
Felder: user, gift { id, name, image, diamonds }, count, totalDiamonds, combo { count, ended }, toGuest
chat
Recht: events.chat
Felder: user (zusätzlich isModerator, isSubscriber, fanLevel), text
like
Recht: events.like
Felder: user (oder null), count, total
follow
Recht: events.follow
Felder: user
share
Recht: events.share
Felder: user
join
Recht: events.join
Felder: user
fanclub
Recht: events.fanclub
Felder: user
viewers
Recht: events.viewers
Felder: count
stream
Recht: stream.status
Felder: status: live, offline oder checking
settings
Recht: keins
Felder: die neuen Einstellungen
context
Recht: keins
Felder: der neue Kontext, zum Beispiel eine neue Größe
ready
Recht: keins
Felder: einmal nach dem Verbinden
*
Recht: keins
Felder: jedes Live-Ereignis von oben
| Typ | Recht | Felder |
|---|---|---|
| gift | events.gift | user, gift { id, name, image, diamonds }, count, totalDiamonds, combo { count, ended }, toGuest |
| chat | events.chat | user (zusätzlich isModerator, isSubscriber, fanLevel), text |
| like | events.like | user (oder 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 oder checking |
| settings | keins | die neuen Einstellungen |
| context | keins | der neue Kontext, zum Beispiel eine neue Größe |
| ready | keins | einmal nach dem Verbinden |
| * | keins | jedes Live-Ereignis von oben |
Jedes Live-Ereignis hat type und id. user ist { handle, nickname, avatar }: handle ist der TikTok-Benutzername ohne @, avatar eine Bild-Referenz für livedeck.image(). Zeig Zuschauer mit ihrem Benutzernamen ("@" + handle). nickname ist der Anzeigename, den der Zuschauer eingetragen hat, oft ein echter Name: nicht anzeigen. Zahlen-IDs von TikTok, E-Mail-Adressen oder Links bekommt ein Widget nie.
{
"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
}Geschenke
- gift.diamonds ist der Coin-Preis EINES Geschenks. count ist die Zahl der neuen Geschenke in diesem Ereignis, totalDiamonds = count × gift.diamonds die Coins, die es dazubringt. Combos sind schon verrechnet: Du addierst count und totalDiamonds, sonst nichts.
- combo ist die ganze Serie, nur zum Anzeigen ("Rose ×7"): combo.count Geschenke bisher, combo.ended, sobald TikTok sie abschließt. combo.count nie aufaddieren und nie damit multiplizieren.
- Coin-Werte kommen immer aus dem Ereignis. Nie eine eigene Preisliste nutzen oder einen Preis aus dem Geschenknamen raten.
- Größtes einzelnes Geschenk: gift.diamonds vergleichen. Top-Supporter / Rangliste: totalDiamonds pro user.handle aufaddieren.
- toGuest ist true, wenn das Geschenk an einen Gast im Multi-Live ging.
- Für ein bestimmtes Geschenk nutzt du eine Einstellung vom Typ gift und vergleichst e.gift.id mit ihrem Wert.
Likes
Im Live bündelt Livedeck Likes alle 500 ms zu einem Ereignis: count ist die Summe in dieser Zeit, total der Gesamtstand des Lives.
Beispiel: Geschenkziel
Passt zur manifest.json auf der Seite „manifest.json: Referenz“. Die Seite braucht ein Element #bar und ein Element #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; // zählt Geschenke; für ein Diamanten-Ziel: e.totalDiamonds
render();
});
livedeck.on("settings", render);
livedeck.ready(render);Beispiel: Chat mit Profilbildern
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);
// Bild-Referenz → lokale Adresse (oder null, dann bleibt es leer)
const url = await livedeck.image(e.user.avatar);
if (url) img.src = url;
});Gut zu wissen
- Namen und Chat-Texte schreiben Zuschauer. Setze sie immer mit textContent ein, nie mit innerHTML.
- Das Widget hat keinen Speicher im Browser: localStorage, sessionStorage, IndexedDB und Cookies sind gesperrt. Halte deinen Zustand im Arbeitsspeicher. Lädt der Nutzer das Overlay neu, fängt das Widget von vorn an.
- Laden geht nur aus deinem eigenen Paket. fetch auf andere Seiten, WebSockets, Frames, Formulare, Pop-ups und Seitenwechsel sind gesperrt.
- Das Overlay fragt alle 2000 ms nach, ob dein Widget noch reagiert. Das SDK antwortet von selbst, solange dein Code den Browser nicht blockiert.
- Im Live bekommt ein Widget höchstens 50 Nachrichten pro Sekunde. Bei sehr vielen Ereignissen haben Geschenke und Chat Vorrang.
- Dein Widget darf höchstens 10 Anfragen pro Sekunde an das Overlay schicken (zum Beispiel livedeck.image), je höchstens 64 KB. Bilder merkt sich das SDK, dieselbe Referenz kostet nur einmal.
- Töne über livedeck.media.play laufen durch Livedecks Audio, also mit Master-Lautstärke und der Ausgabe, die der Nutzer gewählt hat. Töne aus deinem Paket kannst du auch mit <audio> abspielen, die laufen aber an der Livedeck-Lautstärke vorbei.
- Schriften packst du als .woff2 ins Paket und bindest sie mit @font-face und relativem Pfad ein. Bilder darfst du auch selbst erzeugen (Canvas, data:, blob:).
War dieser Artikel hilfreich?