SDK dei widget Livedeck: funzioni ed eventi

Tutto quello che fa l’oggetto livedeck: eventi, impostazioni, immagini, suoni e contesto.

9 min di lettura Aggiornato il 4 nov 2026

L’SDK è una piccola libreria che Livedeck fornisce all’indirizzo di ogni widget sotto /sdk/v1.js. Collega il tuo widget all’overlay e mette a disposizione l’oggetto livedeck.

html
<script src="/sdk/v1.js"></script>

Caricalo prima del tuo codice. Appena la pagina è caricata, l’SDK si annuncia da solo all’overlay. Non devi chiamare niente.

Funzioni

livedeck.on(type, fn)

Chiama fn per ogni evento di questo tipo. Restituisce una funzione che rimuove di nuovo fn.

livedeck.off(type, fn)

Rimuove fn.

livedeck.ready(fn)

Chiama fn appena l’overlay è connesso e le impostazioni sono arrivate. Restituisce anche una Promise.

livedeck.settings

Le impostazioni attuali (sola lettura). Quando l’utente cambia qualcosa, arriva l’evento settings.

livedeck.context

{ mode, format, locale, size, scale, test }. size è la dimensione della pagina in pixel CSS, scale lo zoom del widget ridimensionato (1 di default). mode è live (link OBS), editor (anteprima) o demo (Marketplace).

livedeck.host

{ handle, nickname, avatar } dello streamer, solo con il permesso host.profile, altrimenti null.

livedeck.image(ref)

Trasforma un riferimento a un’immagine (avatar, gift.image) in un indirizzo locale. Promise con l’indirizzo o null.

livedeck.media.play(key, { volume })

Riproduce tramite Livedeck il suono dell’impostazione multimediale key, con il volume generale. volume da 0 a 1. Richiede media.play. Promise con true o false.

livedeck.media.url(key)

Indirizzo locale dell’immagine o della clip dell’impostazione multimediale key. Promise con l’indirizzo o null.

livedeck.version

"1"

Eventi

gift

Permesso: events.gift

Campi: user, gift { id, name, image, diamonds }, count, totalDiamonds, combo { count, ended }, toGuest

chat

Permesso: events.chat

Campi: user (più isModerator, isSubscriber, fanLevel), text

like

Permesso: events.like

Campi: user (o null), count, total

follow

Permesso: events.follow

Campi: user

share

Permesso: events.share

Campi: user

join

Permesso: events.join

Campi: user

fanclub

Permesso: events.fanclub

Campi: user

viewers

Permesso: events.viewers

Campi: count

stream

Permesso: stream.status

Campi: status: live, offline o checking

settings

Permesso: nessuno

Campi: le nuove impostazioni

context

Permesso: nessuno

Campi: il nuovo contesto, ad esempio una nuova dimensione

ready

Permesso: nessuno

Campi: una volta dopo la connessione

*

Permesso: nessuno

Campi: ogni evento live qui sopra

Ogni evento live ha type e id. user è { handle, nickname, avatar }: handle è il nome utente TikTok senza @, avatar un riferimento all’immagine per livedeck.image(). Mostra gli spettatori con il loro nome utente ("@" + handle). nickname è il nome visualizzato inserito dallo spettatore e spesso è un nome reale: non mostrarlo. Un widget non riceve mai ID numerici TikTok, indirizzi e-mail o link.

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
}

Regali

  • gift.diamonds è il prezzo in monete di UN regalo. count è il numero di nuovi regali in questo evento, totalDiamonds = count × gift.diamonds le monete che aggiunge. Le combo sono già conteggiate: somma count e totalDiamonds, nient’altro.
  • combo è l’intera serie, solo da mostrare ("Rose ×7"): combo.count sono i regali finora, combo.ended quando TikTok la chiude. Non sommare mai combo.count e non moltiplicare mai per esso.
  • I valori in monete arrivano sempre dall’evento. Non usare mai un tuo listino prezzi e non indovinare il prezzo dal nome del regalo.
  • Regalo singolo più grande: confronta gift.diamonds. Top supporter / classifica: somma totalDiamonds per ogni user.handle.
  • toGuest è true quando il regalo è andato a un ospite in una LIVE multi-ospite.
  • Per un regalo specifico, usa un’impostazione di tipo gift e confronta e.gift.id con il suo valore.

Mi piace

Durante la LIVE, Livedeck raggruppa i like ogni 500 ms in un solo evento: count è la somma in quell’intervallo, total il conteggio complessivo della LIVE.

Esempio: obiettivo regali

Corrisponde al manifest.json della pagina "Riferimento manifest.json". La pagina ha bisogno di un elemento #bar e di un elemento #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; // counts gifts; for a diamond goal use e.totalDiamonds
  render();
});

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

Esempio: chat con immagini del profilo

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;
});

Buono a sapersi

  • Nomi e testi della chat li scrivono gli spettatori. Inseriscili sempre con textContent, mai con innerHTML.
  • Il widget non ha memoria del browser: localStorage, sessionStorage, IndexedDB e cookie sono bloccati. Tieni lo stato in memoria. Quando l’utente ricarica l’overlay, il widget riparte da zero.
  • Puoi caricare solo dal tuo pacchetto. fetch verso altri siti, WebSocket, frame, moduli, pop-up e navigazione verso altre pagine sono bloccati.
  • L’overlay controlla ogni 2000 ms se il tuo widget risponde ancora. L’SDK risponde da solo, finché il tuo codice non blocca il browser.
  • Durante la LIVE un widget riceve al massimo 50 messaggi al secondo. Con moltissimi eventi, regali e chat hanno la precedenza.
  • Il tuo widget può inviare all’overlay al massimo 10 richieste al secondo (per esempio livedeck.image), ognuna di massimo 64 KB. L’SDK memorizza le immagini, quindi lo stesso riferimento costa una sola volta.
  • I suoni riprodotti con livedeck.media.play passano dall’audio di Livedeck, quindi valgono il volume generale e l’uscita scelta dall’utente. Puoi anche riprodurre suoni dal tuo pacchetto con <audio>, ma così ignorano il volume di Livedeck.
  • Metti i font nel pacchetto come .woff2 e caricali con @font-face e un percorso relativo. Puoi anche generare immagini da solo (canvas, data:, blob:).

Questo articolo ti è stato utile?