Livedeck Widget SDK: Funktionen und Ereignisse

Alles, was das Objekt livedeck kann: Ereignisse, Einstellungen, Bilder, Töne und Kontext.

9 Min. Lesezeit Aktualisiert 4. Nov. 2026

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.

html
<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"

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

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.

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
}

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.

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; // zählt Geschenke; für ein Diamanten-Ziel: e.totalDiamonds
  render();
});

livedeck.on("settings", render);
livedeck.ready(render);

Beispiel: Chat mit Profilbildern

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);
  // 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?