Livedeck widget SDK: functies en events
Alles wat het livedeck-object doet: events, instellingen, afbeeldingen, geluiden en context.
De SDK is een kleine library die Livedeck op het adres van elke widget aanbiedt onder /sdk/v1.js. Hij verbindt je widget met de overlay en levert het livedeck-object.
<script src="/sdk/v1.js"></script>Laad hem vóór je eigen code. Zodra de pagina geladen is, meldt de SDK zich vanzelf bij de overlay. Daarvoor hoef je niets aan te roepen.
Functies
livedeck.on(type, fn)
Roept fn aan bij elk event van dit type. Geeft een functie terug die fn weer verwijdert.
livedeck.off(type, fn)
Verwijdert fn.
livedeck.ready(fn)
Roept fn aan zodra de overlay verbonden is en de instellingen binnen zijn. Geeft ook een Promise terug.
livedeck.settings
De huidige instellingen (alleen-lezen). Als de gebruiker iets wijzigt, komt het settings-event binnen.
livedeck.context
{ mode, format, locale, size, scale, test }. size is de paginagrootte in CSS-pixels, scale de zoom van de geschaalde widget (1 bij standaard). mode is live (OBS-link), editor (preview) of demo (Marketplace).
livedeck.host
{ handle, nickname, avatar } van de streamer, alleen met de permissie host.profile, anders null.
livedeck.image(ref)
Zet een afbeeldingsverwijzing (avatar, gift.image) om in een lokaal afbeeldingsadres. Promise met het adres of null.
livedeck.media.play(key, { volume })
Speelt het geluid uit de media-instelling key af via Livedeck, met het hoofdvolume. volume 0 tot 1. Vereist media.play. Promise met true of false.
livedeck.media.url(key)
Lokaal adres van de afbeelding of clip uit de media-instelling key. Promise met het adres of null.
livedeck.version
"1"
| Aanroep | Wat het doet |
|---|---|
| livedeck.on(type, fn) | Roept fn aan bij elk event van dit type. Geeft een functie terug die fn weer verwijdert. |
| livedeck.off(type, fn) | Verwijdert fn. |
| livedeck.ready(fn) | Roept fn aan zodra de overlay verbonden is en de instellingen binnen zijn. Geeft ook een Promise terug. |
| livedeck.settings | De huidige instellingen (alleen-lezen). Als de gebruiker iets wijzigt, komt het settings-event binnen. |
| livedeck.context | { mode, format, locale, size, scale, test }. size is de paginagrootte in CSS-pixels, scale de zoom van de geschaalde widget (1 bij standaard). mode is live (OBS-link), editor (preview) of demo (Marketplace). |
| livedeck.host | { handle, nickname, avatar } van de streamer, alleen met de permissie host.profile, anders null. |
| livedeck.image(ref) | Zet een afbeeldingsverwijzing (avatar, gift.image) om in een lokaal afbeeldingsadres. Promise met het adres of null. |
| livedeck.media.play(key, { volume }) | Speelt het geluid uit de media-instelling key af via Livedeck, met het hoofdvolume. volume 0 tot 1. Vereist media.play. Promise met true of false. |
| livedeck.media.url(key) | Lokaal adres van de afbeelding of clip uit de media-instelling key. Promise met het adres of null. |
| livedeck.version | "1" |
Events
gift
Permissie: events.gift
Velden: user, gift { id, name, image, diamonds }, count, totalDiamonds, combo { count, ended }, toGuest
chat
Permissie: events.chat
Velden: user (plus isModerator, isSubscriber, fanLevel), text
like
Permissie: events.like
Velden: user (of null), count, total
follow
Permissie: events.follow
Velden: user
share
Permissie: events.share
Velden: user
join
Permissie: events.join
Velden: user
fanclub
Permissie: events.fanclub
Velden: user
viewers
Permissie: events.viewers
Velden: count
stream
Permissie: stream.status
Velden: status: live, offline of checking
settings
Permissie: geen
Velden: de nieuwe instellingen
context
Permissie: geen
Velden: de nieuwe context, bijvoorbeeld een nieuwe grootte
ready
Permissie: geen
Velden: eenmalig na het verbinden
*
Permissie: geen
Velden: elk live-event hierboven
| Type | Permissie | Velden |
|---|---|---|
| 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 (of 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 of checking |
| settings | geen | de nieuwe instellingen |
| context | geen | de nieuwe context, bijvoorbeeld een nieuwe grootte |
| ready | geen | eenmalig na het verbinden |
| * | geen | elk live-event hierboven |
Elk live-event heeft type en id. user is { handle, nickname, avatar }: handle is de TikTok-gebruikersnaam zonder @, avatar een afbeeldingsverwijzing voor livedeck.image(). Toon kijkers met hun gebruikersnaam ("@" + handle). nickname is de weergavenaam die de kijker zelf heeft ingevuld en is vaak een echte naam: toon die niet. Een widget krijgt nooit numerieke TikTok-ID’s, e-mailadressen of links.
{
"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
}Cadeaus
- gift.diamonds is de muntenprijs van ÉÉN gift. count is het aantal nieuwe gifts in dit event, totalDiamonds = count × gift.diamonds de munten die erbij komen. Combo’s zijn al verrekend: tel count en totalDiamonds gewoon op, verder niets.
- combo is de hele reeks, alleen voor weergave („Rose ×7”): combo.count is het aantal cadeaus tot nu toe, combo.ended zodra TikTok de reeks afsluit. Tel combo.count nooit op en vermenigvuldig er nooit mee.
- Muntwaarden komen altijd uit het event. Gebruik nooit je eigen prijslijst en raad nooit een prijs op basis van de cadeaunaam.
- Grootste losse cadeau: vergelijk gift.diamonds. Topsupporter/ranglijst: tel totalDiamonds op per user.handle.
- toGuest is true als het cadeau naar een gast ging in een LIVE met meerdere gasten.
- Voor één specifiek cadeau gebruik je een instelling van het type gift en vergelijk je e.gift.id met de waarde ervan.
Likes
Tijdens de LIVE bundelt Livedeck likes elke 500 ms tot één event: count is de som in die tijd, total het totaal van de hele LIVE.
Voorbeeld: cadeaudoel
Hoort bij de manifest.json op de pagina „manifest.json-referentie”. De pagina heeft een #bar- en een #label-element nodig.
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);Voorbeeld: chat met profielfoto’s
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;
});Goed om te weten
- Namen en chatteksten komen van kijkers. Voeg ze altijd in met textContent, nooit met innerHTML.
- De widget heeft geen browseropslag: localStorage, sessionStorage, IndexedDB en cookies zijn geblokkeerd. Houd je state in het geheugen. Als de gebruiker de overlay herlaadt, begint de widget opnieuw.
- Laden kan alleen uit je eigen pakket. fetch naar andere sites, WebSockets, frames, formulieren, pop-ups en wegnavigeren zijn geblokkeerd.
- De overlay controleert elke 2000 ms of je widget nog reageert. De SDK antwoordt vanzelf, zolang je code de browser niet blokkeert.
- Tijdens de LIVE krijgt een widget maximaal 50 berichten per seconde. Bij heel veel events gaan cadeaus en chat voor.
- Je widget mag maximaal 10 verzoeken per seconde naar de overlay sturen (bijvoorbeeld livedeck.image), elk maximaal 64 KB. De SDK onthoudt afbeeldingen, dus dezelfde referentie telt maar één keer.
- Geluiden die je met livedeck.media.play afspeelt, lopen via de audio van Livedeck, dus het hoofdvolume en de gekozen uitvoer van de gebruiker gelden. Je kunt ook geluiden uit je pakket afspelen met <audio>, maar die omzeilen het volume van Livedeck.
- Zet lettertypen als .woff2 in het pakket en laad ze met @font-face en een relatief pad. Je mag ook zelf afbeeldingen genereren (canvas, data:, blob:).
Was dit artikel nuttig?