SDK dei widget Livedeck: funzioni ed eventi
Tutto quello che fa l’oggetto livedeck: eventi, impostazioni, immagini, suoni e contesto.
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.
<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"
| Chiamata | Cosa fa |
|---|---|
| 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
| Tipo | Permesso | Campi |
|---|---|---|
| gift | events.gift | user, gift { id, name, image, diamonds }, count, totalDiamonds, combo { count, ended }, toGuest |
| chat | events.chat | user (più isModerator, isSubscriber, fanLevel), text |
| like | events.like | user (o 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 o checking |
| settings | nessuno | le nuove impostazioni |
| context | nessuno | il nuovo contesto, ad esempio una nuova dimensione |
| ready | nessuno | una volta dopo la connessione |
| * | nessuno | 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.
{
"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.
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
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?