Livedeck widget SDK: functions and events
Everything the livedeck object does: events, settings, pictures, sounds and context.
The SDK is a small library Livedeck serves at every widget's address under /sdk/v1.js. It connects your widget to the overlay and provides the livedeck object.
<script src="/sdk/v1.js"></script>Load it before your own code. As soon as the page has loaded, the SDK reports to the overlay by itself. You don't need to call anything for that.
Functions
livedeck.on(type, fn)
Calls fn for every event of this type. Returns a function that removes fn again.
livedeck.off(type, fn)
Removes fn.
livedeck.ready(fn)
Calls fn once the overlay is connected and the settings are here. Also returns a Promise.
livedeck.settings
The current settings (read-only). When the user changes something, the settings event arrives.
livedeck.context
{ mode, format, locale, size, scale, test }. size is the page size in CSS pixels, scale the zoom of the resized widget (1 at default). mode is live (OBS link), editor (preview) or demo (Marketplace).
livedeck.host
{ handle, nickname, avatar } of the streamer, only with the host.profile permission, otherwise null.
livedeck.image(ref)
Turns a picture reference (avatar, gift.image) into a local picture address. Promise with the address or null.
livedeck.media.play(key, { volume })
Plays the sound from the media setting key through Livedeck, with the master volume. volume 0 to 1. Needs media.play. Promise with true or false.
livedeck.media.url(key)
Local address of the picture or clip from the media setting key. Promise with the address or null.
livedeck.version
"1"
| Call | What it does |
|---|---|
| livedeck.on(type, fn) | Calls fn for every event of this type. Returns a function that removes fn again. |
| livedeck.off(type, fn) | Removes fn. |
| livedeck.ready(fn) | Calls fn once the overlay is connected and the settings are here. Also returns a Promise. |
| livedeck.settings | The current settings (read-only). When the user changes something, the settings event arrives. |
| livedeck.context | { mode, format, locale, size, scale, test }. size is the page size in CSS pixels, scale the zoom of the resized widget (1 at default). mode is live (OBS link), editor (preview) or demo (Marketplace). |
| livedeck.host | { handle, nickname, avatar } of the streamer, only with the host.profile permission, otherwise null. |
| livedeck.image(ref) | Turns a picture reference (avatar, gift.image) into a local picture address. Promise with the address or null. |
| livedeck.media.play(key, { volume }) | Plays the sound from the media setting key through Livedeck, with the master volume. volume 0 to 1. Needs media.play. Promise with true or false. |
| livedeck.media.url(key) | Local address of the picture or clip from the media setting key. Promise with the address or null. |
| livedeck.version | "1" |
Events
gift
Permission: events.gift
Fields: user, gift { id, name, image, diamonds }, count, totalDiamonds, combo { count, ended }, toGuest
chat
Permission: events.chat
Fields: user (plus isModerator, isSubscriber, fanLevel), text
like
Permission: events.like
Fields: user (or null), count, total
follow
Permission: events.follow
Fields: user
share
Permission: events.share
Fields: user
join
Permission: events.join
Fields: user
fanclub
Permission: events.fanclub
Fields: user
viewers
Permission: events.viewers
Fields: count
stream
Permission: stream.status
Fields: status: live, offline or checking
settings
Permission: none
Fields: the new settings
context
Permission: none
Fields: the new context, for example a new size
ready
Permission: none
Fields: once after connecting
*
Permission: none
Fields: every live event above
| Type | Permission | Fields |
|---|---|---|
| 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 (or 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 or checking |
| settings | none | the new settings |
| context | none | the new context, for example a new size |
| ready | none | once after connecting |
| * | none | every live event above |
Every live event has type and id. user is { handle, nickname, avatar }: handle is the TikTok username without @, avatar a picture reference for livedeck.image(). Show viewers by their username ("@" + handle). nickname is the display name the viewer typed in and is often a real name: don't show it. A widget never gets TikTok number IDs, e-mail addresses or 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
}Gifts
- gift.diamonds is the coin price of ONE gift. count is the number of new gifts in this event, totalDiamonds = count × gift.diamonds the coins it adds. Combos are already netted out: add up count and totalDiamonds, nothing else.
- combo is the whole streak for display only ("Rose ×7"): combo.count gifts so far, combo.ended once TikTok closes it. Never add up combo.count, and never multiply by it.
- Coin values always come from the event. Never use your own price list or guess a price from the gift name.
- Biggest single gift: compare gift.diamonds. Top supporter / leaderboard: add up totalDiamonds per user.handle.
- toGuest is true when the gift went to a guest in a multi-guest LIVE.
- For one specific gift, use a setting of type gift and compare e.gift.id with its value.
Likes
During the LIVE, Livedeck bundles likes every 500 ms into one event: count is the sum in that time, total the LIVE's overall count.
Example: gift goal
Matches the manifest.json on the "manifest.json reference" page. The page needs a #bar and a #label element.
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);Example: chat with profile pictures
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;
});Good to know
- Viewers write names and chat texts. Always insert them with textContent, never with innerHTML.
- The widget has no browser storage: localStorage, sessionStorage, IndexedDB and cookies are blocked. Keep your state in memory. When the user reloads the overlay, the widget starts over.
- Loading only works from your own package. fetch to other sites, WebSockets, frames, forms, pop-ups and navigating away are blocked.
- The overlay checks every 2000 ms whether your widget still responds. The SDK answers by itself as long as your code doesn't block the browser.
- During the LIVE a widget gets at most 50 messages per second. With very many events, gifts and chat come first.
- Your widget may send at most 10 requests per second to the overlay (for example livedeck.image), each at most 64 KB. The SDK remembers pictures, so the same reference only costs once.
- Sounds played with livedeck.media.play go through Livedeck's audio, so the master volume and the output the user picked apply. You can also play sounds from your package with <audio>, but those bypass Livedeck's volume.
- Put fonts into the package as .woff2 and load them with @font-face and a relative path. You may also generate pictures yourself (canvas, data:, blob:).
Was this article helpful?