# Build a Livedeck widget

Instructions for AI assistants and coding agents. Updated 2026-11-04.

Livedeck (https://livedeck.de) is a toolkit for TikTok LIVE streamers. A **widget** is a small web page (HTML, CSS, JavaScript) that runs inside the streamer's overlay in OBS or TikTok LIVE Studio. Livedeck sends it live events (gifts, chat, likes, follows, viewers) through a small SDK, and the widget draws something. Your user wants you to build one.

## Your job

1. **Understand the idea.** Use the description the user gave you. If something essential is missing, ask at most one short question; otherwise choose sensible defaults and say which. Answer in the language the user writes in.
2. **Start from the starter kit** at the end of this file (manifest.json, index.html, style.css, app.js). Keep that structure and change it into the user's widget.
3. **Follow every hard rule below.** Livedeck checks every package automatically and rejects it otherwise.
4. **Check your work** against the checklist below before you hand it over.
5. **Deliver a ZIP.** If you can create files and run commands, write the files into a new folder and zip it with manifest.json at the top level, for example `cd my-widget && zip -r ../my-widget.zip .`. If you can't, show every file in its own code block with its file name, and tell the user to put them in one folder and zip it.
6. **Tell the user how to upload:** Livedeck dashboard › Editor › My widgets › "Upload your own". Widgets are in beta: only accounts Livedeck has enabled can upload (if the button is missing, the user asks Livedeck support). Uploading needs two-factor protection (authenticator app or passkey), and the user must have signed in with it. The widget works in the editor preview right away, with test buttons for gifts, chat, likes and more. In the OBS link it runs after Livedeck's automatic test and an admin's approval.

## Hard rules

- **Everything inside the package.** No address of another site anywhere in HTML, CSS, JavaScript, SVG or JSON: no `http://`, `https://`, `ws://`, `wss://` or `//host`. No CDN libraries, no Google Fonts, no remote images, no analytics or trackers. Fonts go into the package as .woff2 and are loaded with `@font-face` and a relative path.
- **Load the SDK exactly like this**, before your own script: `<script src="/sdk/v1.js"></script>`. Livedeck serves it; it is not part of the package.
- **No network and no storage.** fetch/XMLHttpRequest to other sites, WebSockets, EventSource, frames, forms, pop-ups, navigation, localStorage, sessionStorage, IndexedDB and cookies are all blocked. Keep state in memory.
- **No** iframe, frame, object, embed, portal, base or meta refresh in HTML, and no frames created from JavaScript (`createElement("iframe")`, `"<iframe"` in strings). No scripts, event handlers or foreignObject in SVG files.
- **No WebRTC** (RTCPeerConnection, STUN/TURN servers, iceServers) and no connection hints (dns-prefetch, preconnect, prerender, prefetch). Livedeck removes these APIs inside widgets anyway; using them fails the check.
- **No** eval, new Function, string timers, WebAssembly, crypto mining, obfuscated or minified-only code. Write plain, readable JavaScript. (If you really ship minified code, include the readable sources in a src/ folder.)
- **Viewer text is untrusted.** Insert names and chat texts with `textContent`, never with innerHTML.
- **Usernames, never real names.** Show a viewer as `"@" + e.user.handle` (the TikTok username). `e.user.nickname` is the display name the viewer typed in and is often a real name: never show it, not even as a fallback. The same for `livedeck.host`: show `"@" + host.handle`.
- **Pictures of users and gifts** come as references: get a local address with `await livedeck.image(ref)`. Never put avatar or gift URLs into the page yourself.
- **Ask only for the permissions you use** in manifest.json (`events.gift`, `events.chat`, …). The widget only receives events it has permission for.
- Allowed file types: html, js, mjs, css, json, svg, txt, md, png, jpg, jpeg, webp, gif, mp3, ogg, wav, woff2. Text files in UTF-8. At most 200 files, 2 MB per file and 5 MB in total.

## Runtime and behaviour

- The widget runs in Chromium 127 or newer (OBS Studio 31+, TikTok LIVE Studio, current browsers). Modern CSS (container queries, `cqw` units, `:has()`) is fine.
- **Size and resizing:** design the widget in fixed pixels for `size.default` from manifest.json. When the user makes it bigger or smaller in the editor, Livedeck zooms the whole page with it (text, pictures and spacing grow together), so you don't scale anything yourself. If the user stretches it into another shape, the page gets the extra room in that direction (`100%` widths and heights, flexbox and grid fill it; a list can show more rows). `livedeck.context.size` is the page size in CSS pixels after the zoom and `livedeck.context.scale` the zoom factor; the `context` event fires when they change. Don't zoom the page yourself (no `transform: scale` on the body to fit the box); `cqw`/`vw` units are fine.
- The background is transparent: the stream shows behind the widget. Don't paint a full-page background unless the user wants one. **Never set `color-scheme`** (CSS or `<meta name="color-scheme">`): anything but "normal" makes the browser paint an opaque box behind the widget in OBS. Livedeck's check flags it.
- Events arrive only after `ready`. When the user changes a setting, `livedeck.settings` is already updated when the `settings` event fires.
- There is no storage and no history: after a reload of the overlay the widget starts from zero, and the SDK does not hand over totals from earlier in the stream. For goals and counters, add a setting such as "start value" so the user can continue where they were.
- Gifts, coins and rankings: follow the section "Gifts and coins" below exactly.
- Text settings have one default string (no per-language defaults). Labels can be per language (`{ "de": …, "en": … }`).
- manifest.json, a src/ folder and .md/.txt files are for the review only and are not served: the widget cannot load them at runtime.

## Gifts and coins (get this exactly right)

A gift event looks like this:

```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 }
```

- `gift.diamonds` is the coin price of **one** gift. `count` is the number of **new** gifts in this event and `totalDiamonds` (= count × gift.diamonds) the coins this event **adds**. TikTok sends combos as running ticks (1 → 4 → 7); Livedeck already turns them into new gifts per event, so the three ticks arrive as count 1, 3 and 3.
- `combo` is the whole streak, **for display only** ("Rose ×7"): `combo.count` gifts so far, `combo.ended` once TikTok closes the streak. Never add up `combo.count` and never multiply anything by it.
- **Coins only from the event.** Never use your own price list, never guess a price from the gift name, never invent a value. Use `e.gift.name` and `e.gift.image` as they come.
- **Totals and goals:** add up `e.totalDiamonds` (coins) or `e.count` (number of gifts).
- **Biggest single gift:** compare `e.gift.diamonds` (a combo of 50 roses is not a big gift). If the user wants "biggest gift including its combo", keep the streak per `user.handle` + `gift.id` and compare `combo.count × gift.diamonds`.
- **Top supporter / leaderboard:** keep a map `handle → { avatar, coins }`, add `e.totalDiamonds`, keep the newest avatar, cap the map (for example 5000 viewers), sort only the top few when you render, and show each one as `"@" + handle`.
- **Pictures:** `await livedeck.image(e.gift.image)` (and `e.user.avatar`). Keep showing the old picture until the new one has loaded; if the reference is null or loading fails, show a neutral placeholder that clearly isn't a gift (for example the first letter of the name), never a random gift picture.
- **Guests:** gifts with `toGuest: true` went to a guest in a multi-guest LIVE. Skip them by default and offer a setting to include them.
- **Start state:** before the first gift, show a calm empty state (for example "—" or a short hint), not a made-up number. After a reload the widget starts from zero; offer a "start value" setting for goals.
- **Numbers:** format with `new Intl.NumberFormat(livedeck.context.locale).format(n)`. When a number changes, count it up smoothly over about 0.5 s with requestAnimationFrame (only while it animates), so big jumps read well.
- **Test data:** in the editor, the product page demo and the review (`livedeck.context.test` is true), and in Livedeck's automatic test (which runs like a real LIVE), gifts are made up but realistic: real gift names, pictures and prices, mostly 1–30 coins and now and then up to 29,999 (Lion). Don't treat them differently, but reset your totals when `context.test` changes (listen to the `context` event), so test values never mix with the real LIVE.
- **Storms:** at most 50 events per second reach a widget (short bursts up to 100); more are dropped. Totals are for display, not for payouts.

Reference for a top supporter (biggest single gift or most coins):

```js
const totals = new Map(); // handle -> coins this stream
let top = null;           // { handle, avatar, giftImage, value } — shown as "@" + handle

function onGift(e) {
  if (e.toGuest && !livedeck.settings.includeGuests) return;
  const mode = livedeck.settings.mode; // "single" | "total"
  let value;
  if (mode === "total") {
    if (!totals.has(e.user.handle) && totals.size >= 5000) return;
    value = (totals.get(e.user.handle) || 0) + e.totalDiamonds;
    totals.set(e.user.handle, value);
  } else {
    value = e.gift.diamonds;
  }
  if (top && top.handle === e.user.handle) {
    if (value > top.value) top = { ...top, value, giftImage: e.gift.image };
  } else if (!top || value > top.value) {
    top = { handle: e.user.handle, avatar: e.user.avatar, giftImage: e.gift.image, value };
  } else return;
  scheduleRender(); // at most once per animation frame
}
livedeck.on("gift", onGift);
```

## Testing

There is no local copy of the SDK. The real test is the editor preview after uploading: it is private, works right away and has test buttons. If you want to check the logic before that, use a throwaway page outside the package with a stub like this (never ship it in the ZIP):

```js
// dev-stub.js: load instead of /sdk/v1.js in a local copy of index.html
window.livedeck = (() => {
  const handlers = {};
  const api = {
    settings: {}, // put your manifest defaults here
    context: { mode: "editor", format: "9:16", locale: "en", size: [520, 640], scale: 1, test: true },
    host: null,
    version: "1",
    on(type, fn) { (handlers[type] ||= []).push(fn); return () => api.off(type, fn); },
    off(type, fn) { handlers[type] = (handlers[type] || []).filter((f) => f !== fn); },
    ready(fn) { const p = Promise.resolve(api); if (fn) p.then(fn); return p; },
    image: async () => null,
    media: { play: async () => false, url: async () => null },
    emit(type, e) { for (const fn of [...(handlers[type] || []), ...(handlers["*"] || [])]) fn({ type, ...e }); },
  };
  return api;
})();
// e.g. livedeck.emit("gift", { id: "1", user: { handle: "lena", nickname: "Lena", avatar: null }, gift: { id: 5655, name: "Rose", image: null, diamonds: 1 }, count: 3, totalDiamonds: 3, combo: { count: 3, ended: true }, toGuest: false });
```

## Performance budget

The widget runs next to the streamer's game and OBS, often on slow PCs. The automatic test fires up to 30 gifts, 40 chat messages and 30 likes per second for 10 seconds and measures:

- ready within 3000 ms after loading
- average CPU at most 2 % without events and 15 % under the event storm
- at most 64 MB JavaScript memory and 3000 elements on the page
- no single block longer than 200 ms

During the LIVE the overlay pings the widget every 2000 ms and switches it off if it stops answering. So: remove old elements (cap lists like the starter kit's maxCards), animate with CSS transitions and keyframes instead of JavaScript loops, batch DOM updates, and don't run timers while nothing happens (a one-off `setTimeout` to clean up after an animation is fine). Combine bursts (for example render at most once per animation frame). Effects like confetti: keep it to about 50–80 animated elements at a time, animate only `transform` and `opacity`, and remove them when done.

## Checklist before you deliver

- [ ] manifest.json is valid JSON with manifestVersion 1, a name, a semantic version, sdk "1", entry "index.html", a size and only the permissions the code uses.
- [ ] Viewers are shown as `"@" + handle`; `nickname` appears nowhere on screen.
- [ ] Gift logic follows "Gifts and coins": coins only from `totalDiamonds` / `gift.diamonds`, never `combo.count` added up, no own price list, guests skipped by default, totals reset when `context.test` changes.
- [ ] Every setting the code reads (`livedeck.settings.key`) exists in manifest.json with a default, and the code reacts to the `settings` event.
- [ ] index.html loads `/sdk/v1.js` and then your own script, all paths relative.
- [ ] Searching the package finds no `http:`/`https:`/`ws:` addresses and no `//host` references outside comments, and no `innerHTML` with viewer text, `eval`, `localStorage`, `fetch(` to other sites, `RTCPeerConnection` or `createElement("iframe")`.
- [ ] Old elements are removed; nothing grows without limit.
- [ ] The widget looks good on a transparent background (the overlay shows the stream behind it) at its minimum and maximum size, and when stretched wider or taller than `size.default` (no gaps, nothing cut off).
- [ ] You told the user how to upload and test it.

## Never

- Never ask for, store or use the user's Livedeck password, session, two-factor codes or any token. The user uploads the ZIP themselves.
- Never claim the widget is approved or live. Livedeck's test and an admin decide that.
- Never add links, tracking, ads or anything that collects viewer data.

Downloadable starter kit: https://help.livedeck.de/api/widgets/starter-kit
Human-readable docs: https://help.livedeck.de/pages/widget-api-einstieg


# Reference

## How to build your own TikTok LIVE widgets with the Livedeck API

Source: https://help.livedeck.de/en/pages/widget-api-einstieg

What a widget is, how it runs in your overlay and how to get from the starter kit to a finished widget.

With the Livedeck API you build your own widgets for your overlay: goals, tickers, leaderboards, small games or animations. A widget is a small web page made of HTML, CSS and JavaScript. Livedeck sends it the events from your LIVE (gifts, chat, likes, follows and more), and the widget draws something into your overlay.

(note) Widgets are in beta. At first only enabled accounts can upload. If you want to join, write to us through support.

### How a widget runs

- It runs right inside your normal overlay link (OBS, TikTok LIVE Studio). You don't need a second source.
- Every widget runs shielded in its own frame with its own address. It only sees the events it asks for in its manifest.json and cannot reach your account, your cookies or other widgets.
- Everything the widget needs is inside its package. It loads nothing from other sites: no fonts, images or scripts from the web and no trackers. The browser blocks such attempts during the LIVE as well.
- The widget gets profile and gift pictures through the SDK without loading anything from the web itself.
- If a widget hangs or uses too much CPU, Livedeck switches off only that widget. The rest of your overlay keeps running.

### From the starter kit to a finished widget

1. Download the starter kit and unzip it.
2. Edit manifest.json, index.html, style.css and app.js. "Your first widget" shows every step.
3. Zip the files again.
4. Upload the ZIP in the editor under My widgets › "Upload your own". You need two-factor protection for this (authenticator app or passkey), and you must have signed in with it.
5. Livedeck checks the package and tests the widget automatically. You can try it in the editor preview right away. In the OBS link it runs once an admin has approved it.

[Download the starter kit (ZIP)](https://help.livedeck.de/api/widgets/starter-kit)

### Build it with your AI

Don't code yourself? Describe your idea in a sentence and let Claude, ChatGPT, Cursor or another AI build the widget. The AI reads a guide with all of Livedeck's rules and limits and gives you a ZIP that you upload as described above. Check the result in the editor preview before you use it.

Want to offer your widget to other creators? Sell it on the Livedeck Marketplace. "Review, selling and updates" explains how.

### All developer pages

[Your first widget](https://help.livedeck.de/en/pages/widget-erstes-widget)

[manifest.json reference](https://help.livedeck.de/en/pages/widget-manifest)

[SDK: functions and events](https://help.livedeck.de/en/pages/widget-sdk)

[Rules, performance and check codes](https://help.livedeck.de/en/pages/widget-regeln-leistung)

[Review, selling and updates](https://help.livedeck.de/en/pages/widget-pruefung-verkauf)

## Your first Livedeck widget: from the starter kit to the upload

Source: https://help.livedeck.de/en/pages/widget-erstes-widget

Download the starter kit, change it, upload it as a ZIP and test it in the editor.

The starter kit is a finished widget called "Live Feed": it shows gifts, follows and chat as cards and counts the likes. Build your own from there.

[Download the starter kit (ZIP)](https://help.livedeck.de/api/widgets/starter-kit)

### What's in the package

| File | Purpose |
| manifest.json | Name, version, size, permissions and settings of the widget |
| index.html | The start page. It loads the SDK and your files. |
| style.css | The look |
| app.js | The logic: reacts to events |
| README.md | Quick guide |

### The start page

Every start page loads the SDK from the path /sdk/v1.js. Livedeck serves it at your widget's address; you don't put it into the package yourself. Load all your other files with relative paths.

```html
<!doctype html>
<html lang="en">
<head>
  <meta charset="utf-8">
  <link rel="stylesheet" href="style.css">
  <!-- Livedeck serves the SDK. Everything else lives in your package. -->
  <script src="/sdk/v1.js"></script>
</head>
<body>
  <div id="feed"></div>
  <script src="app.js"></script>
</body>
</html>
```

### Reacting to events

```js
function show(text) {
  const line = document.createElement("p");
  line.textContent = text; // textContent, never innerHTML: names are viewer text
  document.getElementById("feed").prepend(line);
}

livedeck.on("gift", (e) => {
  // "@" + e.user.handle (username), e.gift.name, e.count, e.totalDiamonds
  show("@" + e.user.handle + " sent " + e.count + "× " + e.gift.name);
});

livedeck.on("follow", (e) => {
  show("@" + e.user.handle + " followed you");
});

livedeck.ready(() => {
  // The overlay is connected and the settings are here.
  document.body.style.color = livedeck.settings.accent;
});
```

A widget only gets the events it asks for under permissions in manifest.json. For the example above that is events.gift and events.follow.

### Zip and upload

1. Raise the version in manifest.json (for example from 1.0.0 to 1.0.1) so you can tell your versions apart later.
2. Zip the files. manifest.json must be at the top of the ZIP or inside the one folder that holds everything. Windows: select the files › right-click › Send to › Compressed (zipped) folder. Mac: select the files › right-click › Compress.
3. In the dashboard: Editor › My widgets › "Upload your own". The first time you create a developer profile and accept the rules.
4. After about a minute the check is done. Didn't pass? You see every reason with file and line, or with the measured value. Fix it and upload a new ZIP.
5. Place the widget on the canvas and try it with the test buttons in its settings (gift, chat, likes and more).

(tip) Name your files with a to z, digits, hyphen and underscore only. Livedeck ignores system files such as __MACOSX, .DS_Store or Thumbs.db.

(note) Test events from the editor and the Marketplace arrive with livedeck.context.test = true and made-up viewers. In the OBS link the value is false.

## manifest.json for Livedeck widgets: fields, permissions and error codes

Source: https://help.livedeck.de/en/pages/widget-manifest

Every field, permission and setting type of manifest.json, and what each error code means.

manifest.json describes your widget. Livedeck reads it on upload, builds the editor settings from it and gives the widget only the permissions listed in it. Unknown fields are an error so typos never hide.

```json
{
  "manifestVersion": 1,
  "name": "Gift Goal",
  "version": "1.0.0",
  "sdk": "1",
  "entry": "index.html",
  "description": "A bar that fills up with gifts.",
  "formats": ["9:16", "16:9"],
  "size": { "default": [600, 160], "min": [300, 80], "max": [1080, 400] },
  "permissions": ["events.gift", "media.play"],
  "settings": [
    { "key": "goal", "type": "number", "label": { "de": "Ziel", "en": "Goal" }, "default": 100, "min": 1 },
    { "key": "giftId", "type": "gift", "label": { "de": "Nur dieses Geschenk", "en": "Only this gift" } },
    { "key": "accent", "type": "color", "label": { "de": "Farbe", "en": "Colour" }, "default": "#22c55e" },
    { "key": "doneSound", "type": "media", "label": { "de": "Ton bei Ziel", "en": "Goal sound" }, "accept": "audio" }
  ],
  "locales": ["de", "en"]
}
```

### Fields

| Field | Required | Meaning |
| manifestVersion | yes | Always 1 |
| name | yes | Name of the widget, at most 60 characters |
| version | yes | Version number x.y.z, for example 1.2.0 |
| sdk | yes | SDK version, "1" today |
| entry | no | Start file, index.html by default. Must end in .html. |
| description | no | Short description, at most 300 characters |
| formats | no | ["9:16"], ["16:9"] or both (default: both) |
| size | yes | Size in pixels on the overlay canvas: default, min and max as [width, height] |
| permissions | no | Which data the widget gets (see below) |
| settings | no | Settings users change in the editor (at most 40) |
| locales | no | Languages your widget supports, for example ["de", "en"] |

The canvas is 1080 × 1920 pixels in 9:16 and 1920 × 1080 in 16:9. Sizes go from 16 to 3840 pixels. min and max are the limits when users resize the widget in the editor. Without them, default applies. Build the widget in fixed pixels for default: when users resize it, Livedeck zooms the whole page with the box (text, pictures and spacing grow together). If the box gets another shape than default, the page gets the extra room in that direction, so use 100% widths/heights, flexbox or grid where it should fill. livedeck.context.size is the page size in CSS pixels and livedeck.context.scale the zoom.

### Permissions

Buyers see this list before buying, and the editor shows it under "Gets access to". Only ask for what you really need.

| Permission | What the widget gets |
| events.gift | Gifts (event gift) |
| events.chat | Chat messages (chat) |
| events.like | Likes, bundled (like) |
| events.follow | New followers (follow) |
| events.share | Shares of the LIVE (share) |
| events.join | A viewer joins the LIVE (join) |
| events.fanclub | Fan club joins (fanclub) |
| events.viewers | Viewer count (viewers) |
| stream.status | Live, offline or being checked (stream) |
| media.play | May play sounds from media settings through Livedeck |
| host.profile | The streamer's name and profile picture (livedeck.host) |

### Settings

Every setting has a key, a type and a label. The key starts with a lowercase letter followed by letters, digits or _ (at most 32 characters). A label is text or an object with languages such as {"de": "Farbe", "en": "Colour"}, at most 80 characters. The widget reads the values from livedeck.settings.

| Type | Fields | Value in the widget |
| text | default, maxLength (at most 200) | Text |
| number | default, min, max, step (all optional) | Number |
| range | default, min and max (required), step | Number, shown as a slider in the editor |
| boolean | default | true or false |
| color | default as #rrggbb | Colour as #rrggbb |
| select | options (1 to 50, each with value and label), default | value of the chosen option |
| gift | default (gift ID or null) | Gift ID as a number, or null |
| media | accept: audio, image or video. No default. | true when the user picked a file of their own, otherwise false |

(note) Media settings never give the widget the file's address. Play sounds with livedeck.media.play(key); get pictures and clips with livedeck.media.url(key).

When a value is missing or invalid, the widget gets the default. That way updates with new settings work for everyone who already uses your widget.

### Errors in manifest.json

When the check fails with "manifest.json is invalid", the code and the place are listed below it, for example settings[2].default.

| Code | Meaning |
| manifest_not_object | The file is not a JSON object. |
| manifest_too_large | The file is larger than 64 KB. |
| manifest_invalid_json | Not valid JSON (often one comma too many or too few). |
| unknown_field | This field does not exist. Usually a typo. |
| required | A required field is missing. |
| wrong_type | Wrong type, for example text instead of a list. |
| unsupported_manifest_version | manifestVersion is not 1. |
| unsupported_sdk | sdk is not "1". |
| invalid_name | Name empty, longer than 60 characters or with invisible control characters. |
| invalid_text | Text empty, too long or with invisible control characters. |
| invalid_version | Version not in the form x.y.z (for example 1.0.0). |
| invalid_entry | entry is not a relative path to an .html file. |
| invalid_format | Format is not "9:16" or "16:9". |
| duplicate | Duplicate entry. |
| invalid_size | Size outside 16 to 3840 pixels, or default is not between min and max. |
| unknown_permission | This permission does not exist. |
| too_many_settings | More than 40 settings. |
| invalid_setting_key | key does not match the pattern (see above). |
| unknown_setting_type | This setting type does not exist. |
| invalid_default | default does not fit the type or is outside the bounds. |
| invalid_bounds | min, max, step or maxLength is invalid. |
| invalid_options | options are missing, empty, more than 50, or an option has no value. |
| invalid_media_kind | accept is not audio, image or video. |
| invalid_locale | This language does not exist. Allowed: en, de, tr, fr, es, it, ru, ar, zh-CN, ja, he, pt, nl, pl, uk, ko, hi, id, vi, th. |

## Livedeck widget SDK: functions and events

Source: https://help.livedeck.de/en/pages/widget-sdk

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.

```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

| 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

| 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.

```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:).

## Widget rules: sizes, performance limits and check codes

Source: https://help.livedeck.de/en/pages/widget-regeln-leistung

Sizes, file types, performance limits and every code a check can fail with.

A widget runs in the overlay next to everything else, often on slower PCs. That's why fixed limits apply. Livedeck uses the same numbers in three places: here in the docs, in the automatic test before approval and in the overlay during the LIVE.

### The package

| Limit | Value |
| ZIP file | 5 MB |
| Unpacked in total | 5 MB |
| Single file | 2 MB |
| Files | 200 |
| Path length | 180 characters |
| Folder depth | 8 |
| manifest.json | 64 KB |

Allowed file types: html, js, mjs, css, json, svg, txt, md, png, jpg, jpeg, webp, gif, mp3, ogg, wav, woff2. Text files must be UTF-8. Pictures, sounds and fonts must really be what their extension says.

### What is not allowed

- Addresses of other sites in HTML, CSS, JavaScript, SVG or JSON (http://, https://, ws://, wss:// or //host). Addresses in comments don't fail the check, but the admin sees them.
- iframe, frame, object, embed, portal, base and meta refresh in HTML
- WebRTC (RTCPeerConnection, STUN or TURN servers), frames from JavaScript (createElement("iframe") or "<iframe" in strings) and connection hints such as dns-prefetch or preconnect. Livedeck also switches these features off inside the widget.
- Scripts, event handlers or foreignObject in SVG files
- Encrypted ZIP files, symbolic links and archives inside the archive

The admin also sees hints about eval, new Function, WebAssembly, WebSockets, access to storage or the overlay window, mining patterns and obfuscated or minified code. Hints don't fail the check right away, but they need a good reason. Ship minified code together with readable sources in a src/ folder.

manifest.json, the src/ folder and .md or .txt files are for the review only. Livedeck never serves them to the overlay, so your code cannot load them. Every user gets your widget under an address of their own.

### Performance limits

| Measurement | Limit |
| Ready after the page loaded | 3000 ms |
| Loading the page during the LIVE | 15,000 ms |
| CPU without events (average) | 2 % |
| CPU with very many events (average) | 15 % |
| Memory (JavaScript) | 64 MB |
| Elements on the page | 3000 |
| Longest block at a time | 200 ms |

#### During the LIVE

- The overlay checks every 2000 ms. 3 answers in a row slower than 1000 ms, or 6000 ms without any answer, switch the widget off.
- When the overlay itself was stuck (for example because the tab was in the background), that never counts against your widget.
- A widget that was switched off stays off until the next reload. The editor then shows "Widget stopped".

(tip) Keep the page small: remove old elements (the starter kit shows at most maxCards cards), use CSS animations instead of JavaScript loops and don't run timers while nothing happens.

### Check codes

When a check fails, the editor or the seller studio shows a list of reasons. Every single code is listed here.

#### ZIP file

| Code | Meaning |
| zip_too_large | The ZIP file is larger than 5 MB. |
| zip_total_too_large | Larger than 5 MB once unpacked. |
| zip_file_too_large | A file is larger than 2 MB. |
| zip_too_many_files | More than 200 files. |
| zip_not_zip | Not a ZIP file, or an empty one. |
| zip_multi_disk | Split into several parts. Pack everything into one file. |
| zip64_unsupported | ZIP64 is not supported. |
| zip_trailing_data | There is extra data after the end of the ZIP file. |
| zip_corrupt | The ZIP file is damaged. |
| zip_encrypted | The ZIP file is password-protected. |
| zip_unsupported_method | Compression method not supported. Stored (no compression) and Deflate (the default) are allowed. |
| zip_header_mismatch | The archive contradicts itself. |
| zip_overlap | Files overlap inside the archive. |
| zip_crc_mismatch | Checksum wrong, a file is damaged. |
| zip_symlink | Symbolic link in the package. |
| zip_bad_name | Invalid file name: non-ASCII without UTF-8, ../, absolute paths, special characters, longer than 180 characters or deeper than 8 folders. |
| zip_duplicate_name | A file appears twice in the archive. |
| zip_nested_archive | An archive inside the archive (for example a ZIP in the ZIP). |

#### Files and content

| Code | Meaning |
| manifest_missing | manifest.json is missing. It must be at the top of the ZIP or inside its only folder. |
| manifest_invalid | manifest.json is invalid. The errors are listed below it (codes in "manifest.json reference"). |
| entry_missing | The start file named in entry is not in the package. |
| file_type_not_allowed | This file type is not allowed. |
| file_content_mismatch | The content does not match the extension (for example a JPG named .png). |
| file_not_utf8 | The text file is not saved as UTF-8. |
| file_empty | The file is empty. |
| external_reference | The file contains the address of another site (with the line). |
| forbidden_markup | HTML that is not allowed (iframe, frame, object, embed, portal, base, meta refresh) or script in an SVG file. |
| forbidden_api | Code that would get around the blocks to the network: WebRTC (RTCPeerConnection, STUN/TURN), frames from JavaScript (createElement("iframe"), "<iframe" in strings) or connection hints (dns-prefetch, preconnect, prerender, prefetch). |

#### Automatic test

test_failed means the automatic test broke at least one limit. The single reasons are listed below it, each with the measured value and the limit.

| Code | Meaning |
| perf_no_ready | The widget never reported to the overlay after loading. Usually <script src="/sdk/v1.js"> is missing or the page never finishes loading. |
| perf_ready_slow | Ready too late: more than 3000 ms after the page loaded. |
| perf_unresponsive | Does not answer the overlay's check, or too slowly (the code blocks the browser). |
| perf_navigated | The widget navigated away or reloaded its page. |
| perf_flood | The widget sends far too many messages to the overlay. |
| perf_idle_cpu | More than 2 % CPU while nothing happens. |
| perf_storm_cpu | More than 15 % CPU with lots of events. |
| perf_heap | More than 64 MB of memory. |
| perf_dom | More than 3000 elements on the page. |
| perf_long_task | Blocks the browser for longer than 200 ms at a time. |
| network_attempt | Tries to load something from another site (the host is shown). |
| runtime_errors | Only a hint, not a reason to fail: JavaScript errors during the test. The admin sees the first one. |

## How widget review, selling on the Marketplace and updates work

Source: https://help.livedeck.de/en/pages/widget-pruefung-verkauf

What happens after uploading, how to sell widgets on the Marketplace and how updates reach your buyers.

### What happens after uploading

1. Package check: ZIP, files, manifest.json and the rules. This takes seconds.
2. Automatic test: Livedeck opens your widget in its own browser, just like the OBS link. It waits 5 seconds without events, sends every kind of event your widget asks for, and then very many at once for 10 seconds (about 30 gifts, 40 chat messages and 30 likes per second). Meanwhile it measures the performance limits, watches for attempts to load from other sites and takes screenshots.
3. Comparison: an AI compares the screenshots with the name and description. It decides nothing; it helps the admin.
4. Preview: the marketplace shows your real widget as the preview, looping with test events and a watermark. You don't upload a preview image; the still picture for the cart and library is a screenshot from the test.
5. Approval: an admin looks at the test report, screenshots and code, and for updates the changes since the last version, then approves. A human reviews every version.

Didn't pass? You see every reason (see "Rules, performance and check codes"). That version stays locked; upload a fixed one.

### Your own widgets

- You upload them in the editor under My widgets. Only you see them.
- They run in the editor preview right away and in the OBS link after approval.
- New version: "Upload new version". Until it is approved, the OBS link keeps running the old version.

### Selling on the Marketplace

1. Open the seller studio on the Marketplace, create a new product and pick the type Widget. You need two-factor protection and a sign-in with your code or passkey.
2. Upload the ZIP and wait for the check.
3. Upload a cover image (required for widgets) and fill in text, price and category.
4. Submit the widget. After approval it is listed on the Marketplace.

- For paid widgets, set up your payouts in the studio. Livedeck keeps 12% + €0.30 per sale and covers the payment fees. Payouts arrive once a month, from a €20 balance.
- On the product page your widget runs as a live preview with test events. Buyers see which data it gets before buying.
- Buyers get a licence to use the widget in their overlay. They don't download the code; your package stays sealed at Livedeck.
- Bought widgets run without a limit on every plan, FREE included.

### Updates

Upload a new version in the studio. It goes through the same review. After approval every buyer gets it automatically, at the latest the next time their overlay loads. Their settings are kept; new settings start with their default.

### Blocking

(warning) Widgets that grab data, deceive or contain malicious code are blocked by Livedeck at once and for good. The widget stops running in every overlay, every buyer gets their money back, and the seller bears the cost, including the Livedeck commission. It is deducted from later payouts.

# Starter kit files

### app.js

```js
// Live Feed: a starter widget for the Livedeck API v1.
// Docs: Livedeck help centre, section "Developers".
(function () {
  "use strict";

  var cards = document.getElementById("cards");
  var likes = 0;

  function applySettings(s) {
    document.documentElement.style.setProperty("--accent", s.accent || "#22c55e");
    document.getElementById("title").textContent = s.title || "Live";
    document.body.className = s.theme === "glass" ? "theme-glass" : "";
  }

  // Pictures (avatars, gift icons) arrive as references; livedeck.image() turns them into a local blob URL.
  function picture(ref, className) {
    var img = document.createElement("img");
    img.className = className;
    img.alt = "";
    if (ref) livedeck.image(ref).then(function (url) { if (url) img.src = url; });
    return img;
  }

  function addCard(kind, user, what, giftRef, count) {
    var li = document.createElement("li");
    li.className = "card card--" + kind;
    li.appendChild(picture(user && user.avatar, "card__avatar"));
    var text = document.createElement("span");
    text.className = "card__text";
    var name = document.createElement("span");
    name.className = "card__name";
    name.textContent = user ? "@" + user.handle : ""; // the TikTok username, never the display name
    var line = document.createElement("span");
    line.className = "card__what";
    line.textContent = what;
    text.appendChild(name);
    text.appendChild(line);
    li.appendChild(text);
    if (giftRef) li.appendChild(picture(giftRef, "card__gift"));
    if (count > 1) {
      var c = document.createElement("span");
      c.className = "card__count";
      c.textContent = "×" + count;
      li.appendChild(c);
    }
    cards.insertBefore(li, cards.firstChild);
    var max = Number(livedeck.settings.maxCards) || 4;
    while (cards.children.length > max) cards.removeChild(cards.lastChild);
  }

  livedeck.on("gift", function (e) {
    addCard("gift", e.user, e.gift.name, e.gift.image, e.count);
    if (livedeck.settings.giftSound) livedeck.media.play("giftSound", { volume: 0.8 });
  });
  livedeck.on("follow", function (e) { addCard("follow", e.user, "followed", null, 1); });
  livedeck.on("chat", function (e) { if (livedeck.settings.showChat) addCard("chat", e.user, e.text, null, 1); });
  livedeck.on("like", function (e) {
    likes = Math.max(likes + e.count, e.total);
    document.getElementById("likes").textContent = "♥ " + likes.toLocaleString();
  });
  livedeck.on("settings", applySettings);
  livedeck.ready(function () { applySettings(livedeck.settings); });
})();
```

### index.html

```html
<!doctype html>
<html lang="en">
<head>
  <meta charset="utf-8">
  <meta name="viewport" content="width=device-width, initial-scale=1">
  <title>Live Feed</title>
  <link rel="stylesheet" href="style.css">
  <!-- The Livedeck SDK, served by the widget host. Everything else must be inside this package. -->
  <script src="/sdk/v1.js"></script>
</head>
<body>
  <main id="feed" class="feed">
    <header class="feed__title"><span class="dot"></span><span id="title">Live</span><span id="likes" class="likes"></span></header>
    <ol id="cards" class="cards"></ol>
  </main>
  <script src="app.js"></script>
</body>
</html>
```

### manifest.json

```json
{
  "manifestVersion": 1,
  "name": "Live Feed",
  "version": "1.0.0",
  "sdk": "1",
  "entry": "index.html",
  "description": "Shows gifts, follows and chat as cards.",
  "formats": ["9:16", "16:9"],
  "size": { "default": [520, 640], "min": [260, 200], "max": [1080, 1920] },
  "permissions": ["events.gift", "events.follow", "events.chat", "events.like", "media.play"],
  "settings": [
    { "key": "title", "type": "text", "label": { "de": "Überschrift", "en": "Title" }, "default": "Live", "maxLength": 40 },
    { "key": "accent", "type": "color", "label": { "de": "Akzentfarbe", "en": "Accent colour" }, "default": "#22c55e" },
    { "key": "showChat", "type": "boolean", "label": { "de": "Chat anzeigen", "en": "Show chat" }, "default": true },
    { "key": "maxCards", "type": "range", "label": { "de": "Karten gleichzeitig", "en": "Cards at once" }, "default": 4, "min": 1, "max": 8, "step": 1 },
    { "key": "theme", "type": "select", "label": { "de": "Design", "en": "Style" }, "default": "dark",
      "options": [ { "value": "dark", "label": { "de": "Dunkel", "en": "Dark" } }, { "value": "glass", "label": { "de": "Glas", "en": "Glass" } } ] },
    { "key": "giftSound", "type": "media", "label": { "de": "Ton bei Geschenken", "en": "Gift sound" }, "accept": "audio" }
  ],
  "locales": ["de", "en"]
}
```

### style.css

```css
:root { --accent: #22c55e; }
html, body { margin: 0; height: 100%; background: transparent; overflow: hidden; }
body { font: 600 clamp(14px, 4.2cqw, 28px)/1.25 system-ui, -apple-system, "Segoe UI", sans-serif; color: #fff; container-type: size; }
.feed { box-sizing: border-box; height: 100%; padding: 4%; display: flex; flex-direction: column; gap: 3%; }
.feed__title { display: flex; align-items: center; gap: .5em; font-size: 1.1em; text-transform: uppercase; letter-spacing: .08em; }
.dot { width: .6em; height: .6em; border-radius: 50%; background: var(--accent); box-shadow: 0 0 .8em var(--accent); }
.likes { margin-inline-start: auto; font-size: .8em; opacity: .8; }
.cards { list-style: none; margin: 0; padding: 0; display: flex; flex-direction: column; gap: .5em; }
.card { display: flex; align-items: center; gap: .6em; padding: .55em .7em; border-radius: .8em; background: rgba(0, 0, 0, .72); border: 1px solid rgba(255, 255, 255, .12); animation: in .35s ease-out; }
.theme-glass .card { background: rgba(255, 255, 255, .14); backdrop-filter: blur(8px); }
.card__avatar { width: 2.2em; height: 2.2em; border-radius: 50%; object-fit: cover; flex: none; background: rgba(255, 255, 255, .1); }
.card__text { min-width: 0; flex: 1; }
.card__name { display: block; overflow: hidden; white-space: nowrap; text-overflow: ellipsis; }
.card__what { display: block; font-weight: 500; font-size: .8em; opacity: .8; overflow: hidden; white-space: nowrap; text-overflow: ellipsis; }
.card__gift { width: 2em; height: 2em; flex: none; object-fit: contain; }
.card--gift { border-color: var(--accent); }
.card__count { color: var(--accent); font-weight: 800; }
@keyframes in { from { transform: translateY(-.6em); opacity: 0; } to { transform: none; opacity: 1; } }
@media (prefers-reduced-motion: reduce) { .card { animation: none; } }
```
