Livedeck widget SDK: functions and events

Everything the livedeck object does: events, settings, pictures, sounds and context.

9 min read Updated Nov 4, 2026

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.

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

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

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.

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
}

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.

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; // counts gifts; for a diamond goal use e.totalDiamonds
  render();
});

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

Example: chat with profile pictures

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