TokElementsDOCS
WIDGET SDK / V1

Documentazione SDK widget per TikTok LIVE

Crea widget personalizzati per TikTok LIVE con l'SDK JavaScript di TokElements. Eventi live, azioni, impostazioni, regole sandbox ed esempi interattivi.

01

Primi passi

1
Scrivi markup e stile

Le schede HTML e CSS disegnano il widget. Il riquadro è trasparente e sta sopra il video: non usare mai uno sfondo pieno e opaco.

2
Reagisci agli eventi

Nella scheda JS iscriviti con TE.on('gift', fn). window.TE è già caricato: niente import, niente setup.

3
Prova e aggiungi

Usa Simulate o i pulsanti Fire per l'anteprima offline, poi Aggiungi all'overlay. Oppure lascia che lo crei Claude via MCP.

Il tuo primo widget: un ringraziamento per i regali· modifica il JS, l'anteprima reagisce in tempo reale
var box = document.getElementById('box');
TE.on('gift', function (ev) {
  box.textContent = ev.user.name + ' sent ' + ev.gift.name + '!';
  box.classList.remove('pop'); void box.offsetWidth; box.classList.add('pop');
});
Anteprima live
02

Collega Claude (MCP)

Crea e modifica questi widget direttamente da Claude Desktop o Claude Code. Genera un token, aggiungi il connettore e Claude potrà usare questi strumenti sul tuo account:

get_docsLa guida completa + tutti i trigger e le azioni (Claude la legge per prima).
list_widgetsElenca i tuoi widget salvati con i loro id.
get_widgetRecupera html / css / js di un widget.
create_widgetCrea un nuovo widget HTML da nome + html/css/js.
update_widgetModifica un widget esistente.
delete_widgetElimina un widget tramite id.
list_templatesElenca i template integrati da copiare.
get_templateLegge html/css/js di un template.
create_from_templateCopia un template in un nuovo widget.
list_community_templatesSfoglia i widget pubblicati dalla community.
install_community_templateInstalla una copia privata e modificabile di un template della community.
Caricamento…
03

L'SDK TE

Tutto ciò che fa un widget passa dall'oggetto globale window.TE.

TE.on(type, fn)

Iscriviti a un evento live. `type` è uno dei trigger qui sotto; `fn(ev)` viene eseguita ogni volta che succede.

TE.on('*', fn)

Ricevi ogni evento. `fn(ev, type)` riceve il payload e il nome dell'evento.

TE.off(type, fn)

Rimuove un handler registrato in precedenza.

TE.onGift(name, fn)

Scatta solo per i regali il cui nome corrisponde (sottostringa, maiuscole/minuscole ignorate). Ometti `name` per ricevere ogni regalo.

TE.onSticker(idOrUrl, fn)

Scatta solo per una specifica emote / sticker degli abbonati, riconosciuta dal suo id TikTok, URL immagine o source.

TE.rules.allowUser / allowGift

Filtri di idoneità riutilizzabili per ruoli, liste consentiti/bloccati, nome del regalo e valore minimo in monete.

TE.metrics

L'ultimo snapshot della live (spettatori, like, monete, follower, topGifters…). Arriva anche tramite TE.on('metrics', fn).

TE.demo

True dove il widget viene mostrato in vetrina (galleria, riquadri di anteprima, l'interruttore Demo del builder). False in un overlay live e mentre fai test nel builder o nell'editor overlay, dove compare solo ciò che invii tu o ciò che arriva dalla live. Ogni widget si presenta da solo: metti esempi che sembrino eventi reali (vere immagini dei regali, nomi, avatar) in un blocco if (TE.demo), passando dal codice reale del widget. Un widget con questo blocco non riceve eventi di anteprima dall'host, quindi niente scatta due volte.

TE.defineSettings([...])

Dichiara controlli che lo streamer può regolare; restituisce i valori attuali (default uniti alle scelte dello streamer).

TE.settings

L'oggetto con i valori attuali delle impostazioni (stessa forma restituita da defineSettings).

TE.on('settings', fn)

Viene eseguito quando lo streamer cambia un'impostazione dal vivo: ridisegna con i nuovi valori.

TE.state.get/set/increment

Valori atomici basati su Promise per totali e stato di gioco condiviso.

TE.collection.*

Partecipanti (iscrizione singola) e classifiche gestiti dal server: join, increment, list, count, remove e clear.

TE.queue.*

Code FIFO limitate gestite dal server per media, richieste e azioni avviate dagli spettatori.

TE.shared.*

Fa condividere a più widget un unico namespace di stato del canale con un nome; i widget non collegati restano isolati.

TE.random.draw(name, opts)

Estrae in modo sicuro uno o più vincitori da una collezione e registra il risultato.

TE.cooldown.claim(scope, user, ms)

Riserva in modo atomico un cooldown globale o per utente; restituisce claimed e retryAfterMs.

TE.timer.*

Avvia, metti in pausa, azzera e leggi un timer persistente che sopravvive ai ricaricamenti.

TE.points.trySpend(user, amount, reason)

Controlla e scala i punti in un'unica transazione; verifica sempre result.ok prima di eseguire un'interazione a pagamento.

04

Trigger

Eventi live che puoi ascoltare. Ogni user contiene { id, name, username, avatar, roles }.

TE.on('gift')

Uno spettatore ha inviato un regalo. coins = totale della combo; streakEnd indica che la combo è finita.

{ user, gift: { name, image|null, coins, repeat, combo, streakEnd } }
TE.on('follow')

Uno spettatore ha seguito l'account.

{ user }
TE.on('subscribe')

Uno spettatore si è abbonato. months = quanti mesi di fila.

{ user, months }
TE.on('share')

Uno spettatore ha condiviso la live.

{ user }
TE.on('chat')

Un messaggio in chat. emotes = URL delle immagini delle emote abbonati presenti nel messaggio.

{ user, comment, emotes:[url,…] }
TE.on('like')

Uno spettatore ha inviato like. count = questa raffica; total = totale progressivo.

{ user, count, total }
TE.on('join')

Uno spettatore è entrato nella stanza. isTop = è entrato un top gifter.

{ user, isTop }
TE.on('sticker')

Un'emote abbonati o uno sticker a schermo inviato in live. url = l'immagine dell'emote; id = il suo id TikTok.

{ user|null, id|null, url, source }
TE.on('metrics')

L'ultimo snapshot della live. TE.metrics lo contiene; l'evento scatta a ogni aggiornamento. hostNick e hostAvatar sono il nome e la foto profilo dello streamer.

{ live, viewers, likes, followers, coins, hostNick, hostAvatar, topGifters:[…], … }
TE.on('milestone')

È stato superato un traguardo tondo (like, monete, follower, abbonati).

{ metric, value, label }
TE.on('poll')

Il sondaggio live nativo di TikTok: voti reali, dall'inizio alla fine.

{ state:'start'|'update'|'end', title, options:[{text,votes}], endsAt }
TE.on('battle')

Aggiornamenti delle battle LinkMic: carte battle, fan ticket, dimensioni delle squadre.

{ card|null, tickets|null, armies|null, battleId|null }
TE.on('rank')

Posizione nella classifica oraria e momenti di salita.

{ rank|null, from|null, to|null, countdown|null }
TE.on('envelope')

Una busta rossa / un forziere lanciato nella live.

{ }
TE.on('pinned')

L'host ha fissato un commento.

{ text }
TE.on('deleted')

Un moderatore ha rimosso un messaggio in chat (l'id corrisponde all'evento chat precedente).

{ id }
TE.on('streamState')

La live è iniziata o è finita.

{ live }
TE.on('apiEvent')

Un evento personalizzato inviato tramite la Event API. Ascolta apiEvent oppure direttamente il suo nome personalizzato.

{ name, data }
TE.on('nowPlaying')

Il brano Spotify attuale dello streamer PIÙ la coda dei prossimi. Scatta alla connessione e ogni volta che cambiano brano, stato di riproduzione, avanzamento o coda. playback è null quando non suona niente; queue sono i brani in arrivo.

{ connected, playback: { isPlaying, progressMs, durationMs, title, artists:[…], album, artwork|null } | null, queue:[{ title, artist, artwork|null, durationMs }] }
Solo un regalo o una emote specifica
TE.onGift('Rose', function (ev) { /* … */ });
TE.onSticker('<sticker id>', function (ev) { /* … */ });

Le emote del tuo canale sono nel widget builder: apri Simula eventi, scegli Sticker e selezionane una. L'evento di prova porta il vero id e il vero URL dell'immagine, così un handler basato su uno dei due viene testato con l'emote reale.

05

Azioni

Cosa può fare il tuo widget in risposta: normali API del browser, pronte da incollare.

Mostra un'immagine

Fai apparire un'immagine a schermo: l'artwork del regalo/emote, un file caricato o qualsiasi URL. Sparisce da sola dopo qualche secondo.

// Show an image, then fade it out
TE.on('gift', function (ev) {
  var img = document.createElement('img');
  img.src = ev.gift.image;                 // ← any image URL works
  img.style.cssText = 'position:absolute;left:50%;top:50%;transform:translate(-50%,-50%);max-width:60%';
  document.body.appendChild(img);
  setTimeout(function () { img.remove(); }, 4000);   // ← how long it stays
});
Riproduci un suono

Riproduci un audio su un evento. Esponi un'impostazione sound così lo streamer sceglie il proprio file, senza toccare il codice.

// Play a sound the streamer chose in settings
var s = TE.defineSettings([{ key: 'sfx', label: 'Alert sound', type: 'sound', default: '' }]);
TE.on('settings', function (ns) { s = ns; });
TE.on('gift', function (ev) {
  if (s.sfx) { var a = new Audio(s.sfx); a.volume = 0.8; a.play(); }
});
Mostra / anima testo

Scrivi testo dinamico e riavvia un'animazione CSS alternando una classe.

// Announce the event with a CSS pop animation
var box = document.getElementById('box');   // your element in the HTML tab
TE.on('follow', function (ev) {
  box.textContent = ev.user.name + ' followed!';
  box.classList.remove('pop'); void box.offsetWidth; box.classList.add('pop');
});
Mostra una statistica live

Collega un numero a schermo a una metrica live (spettatori, like, monete, follower), aggiornato in automatico.

// Keep a number in sync with the live stream
TE.on('metrics', function (m) {
  document.getElementById('count').textContent = m.viewers.toLocaleString();
});
Leggilo ad alta voce (TTS)

Fai pronunciare un evento con la sintesi vocale del browser. Perfetto per ringraziare regali o follow.

// Text-to-speech shout-out
TE.on('gift', function (ev) {
  var u = new SpeechSynthesisUtterance(ev.user.name + ' sent ' + ev.gift.name);
  speechSynthesis.speak(u);
});
Anteprima (TE.demo)

Ogni widget si presenta nella galleria e nel builder: esempi che sembrano eventi reali, con vere immagini dei regali, nomi e avatar. In live TE.demo è false e compaiono solo eventi reali.

// Preview samples through the real code path. Never on a live overlay.
if (TE.demo) {
  var GIFTS = [
    { name: 'Rose', coins: 1, image: 'https://p16-webcast.tiktokcdn.com/img/maliva/webcast-va/eba3a9bb85c33e017f3648eaf88d7189~tplv-obj.png' },
    { name: 'Perfume', coins: 20, image: 'https://p16-webcast.tiktokcdn.com/img/maliva/webcast-va/20b8f61246c7b6032777bb81bf4ee055~tplv-obj.png' }
  ];
  var NAMES = ['lunaa', 'nightowl_gaming_official'], n = 0;
  function sample() {
    n++;
    onGift({ user: { name: NAMES[n % 2], avatar: window.__TE_AVATAR }, gift: GIFTS[n % 2] });
  }
  sample();
  setInterval(sample, 6000);
}
Ricorda le cose (TE.store)

Persistenza sincrona semplice per lo stato visivo. Per partecipanti, acquisti e punteggi condivisi usa il runtime transazionale.

// Persistent state: survives OBS reloads
var total = TE.store.get('total', 0);          // read (with default)
TE.on('gift', function (ev) {
  total += ev.gift.coins;
  TE.store.set('total', total);                 // write (auto-saved)
  render();
});
Reagisci ai comandi in chat

Comandi chat a corrispondenza esatta più collezioni atomiche rendono sicuri iscrizioni, voti e giri di ruota.

// One server-authoritative entry per viewer.
// A function keyword reads s.command on every message, so the
// streamer can change the command in settings without a reload.
TE.onCommand(function () { return s.command || '!join'; }, function (c) {
  TE.collection.join('entrants', c.user.id, c.user).then(function (result) {
    if (result.joined) renderCount(result.count);
  });
});
Avvia azioni della live (TE.act)

Richiedi alert dell'overlay, suoni, TTS, contatori, tempo subathon o cambi scena OBS direttamente da un widget.

// One call, one stream action
TE.act({ id: 'tts', message: 'New high score!' });
TE.act({ id: 'points', user: ev.user, amount: 50 });
Assegna punti agli spettatori

Controlla, spendi o assegna punti fedeltà in modo transazionale e ricevi il saldo risultante.

// Only spin after the points were really debited
TE.onCommand(function () { return s.command || '!spin'; }, function (ev) {
  TE.points.trySpend(ev.user, 50, 'Wheel spin').then(function (result) {
    if (result.ok) spin();
    else showMissing(result.missing);
  });
});
Crea giochi equi

Stato atomico, collezioni, estrazioni casuali sicure, cooldown e timer persistenti: sicuri anche con browser source duplicate.

// Fair draw from a server-owned entrant collection
TE.random.draw('entrants', { count: 1 }).then(function (result) {
  if (result.ok) reveal(result.winners[0].value);
});
Aggiungi controlli per lo streamer

Esponi testi, colori, numeri, interruttori: lo streamer li regola dal vivo nell'editor overlay, senza codice.

// No-code controls for whoever uses the widget
var s = TE.defineSettings([
  { key: 'title',  label: 'Title', type: 'text',  default: 'Goal' },
  { key: 'accent', label: 'Color', type: 'color', default: '#FF2E4D' },
]);
document.body.style.setProperty('--accent', s.accent);
TE.on('settings', function (ns) { s = ns; /* re-render with new values */ });
06

Impostazioni dello streamer

Dichiara i controlli con TE.defineSettings([...]) e chi usa il widget li regola dal vivo nell'editor overlay, senza codice. Ogni campo:

Un widget posizionato con uno o più campi 'button' mostra quelle azioni nelle sue impostazioni dentro l'Editor overlay. Il Widget Builder mostra gli stessi pulsanti per testare l'anteprima in sicurezza mentre scrivi il codice.

tipomostravalore
'text'Campo di testo su una rigastring
'number'Campo numericonumber
'color'Selettore colorestringa hex, es. "#FF2E4D"
'select'Menu a tendina (richiede options: [...])una delle opzioni
'toggle'Interruttore on/offboolean
'range'Cursore (min / max / step)number
'button'Pulsante di azione dichiarativoincrement, set o toggle: JSON validato, mai codice della dashboard
'sound'Selettore tra i suoni caricati dallo streamer + Carical'URL del file scelto ("" = nessuno)
'image'Selettore tra le immagini caricate dallo streamer + Carical'URL del file scelto ("" = nessuno)
'model'Selettore tra i modelli 3D (.glb) caricati dallo streamer + Carical'URL del .glb scelto ("" = nessuno), per TE.lib('three')
var s = TE.defineSettings([
  { key: 'title',  label: 'Title', type: 'text',   default: 'Follower goal' },
  { key: 'target', label: 'Goal',  type: 'number', default: 100 },
  { key: 'accent', label: 'Color', type: 'color',  default: '#FF2E4D' },
  { key: 'reset',  label: 'Reset', type: 'button', default: 0,
    action: { type: 'increment', step: 1 }, confirm: true, tone: 'danger' },
]);
// re-render when the streamer changes something live
var lastReset = s.reset;
TE.on('settings', function (ns) {
  s = ns;
  if (ns.reset !== lastReset) { lastReset = ns.reset; resetCounter(); }
  render();
});

Le definizioni dei controlli sono dati validati. L'action di un pulsante accetta solo increment, set o toggle. HTML, codice di callback e URL arbitrari vengono rifiutati o ignorati dal renderer della dashboard.

07

Motore 3D

3D vero in qualsiasi widget: await TE.lib('three') carica TE3D, un motore three.js incluso in TokElements (niente CDN, funziona offline). Trasforma il nome di qualsiasi spettatore in lettere 3D estruse, arabo compreso, e aggiunge materiali, look fumetto, modelli 3D caricati ed effetti cinematografici. Il canvas resta trasparente in OBS.

T.stage({ bloom, look })

Un canvas 3D trasparente a tutta dimensione per widget, con riflessi da studio, bagliore (bloom) e un ciclo di rendering. look sceglie lo stile di post-processing.

T.text3d(text, opts)

Vero testo estruso (profondità + smusso) da qualsiasi nome. L'arabo viene composto da destra a sinistra, le lettere decorative vengono normalizzate, le emoji saltate: passa lo @username come riserva. Opzioni: size, depth, bevel, maxWidth, color, style ('cinematic', 'bold', 'tech', 'comic'), material, outline, perLetter.

T.letters(text, { effect })

Entrate lettera per lettera per il testo creato con perLetter: true: 'drop', 'pop', 'spin', 'rise' o 'scatter'.

T.wave(stage, text)

Tiene in movimento il testo perLetter con un'onda che attraversa le lettere.

T.animate(obj, to, opts)

Anima posizione, rotazione, scala e opacità con easing ('outBack', 'outBounce', 'outElastic', …). Restituisce una Promise.

stage.look() · shake() · glitch()

Cambia il look dell'intera scena, scuote la camera all'impatto o fa glitchare l'immagine.

T.model(url, { size })

Carica un modello .glb caricato, scalato e centrato; stage.add(model) riproduce le sue animazioni. Richiedilo con un'impostazione 'model'.

stage.onFrame(fn)

Chiama fn a ogni frame con il passo temporale e i secondi trascorsi. Restituisce off().

T.stage({ parent }) · stage.frame(w, h)

parent mette la vista 3D dentro un elemento, accanto al normale HTML. frame() adatta un riquadro di unità del mondo a qualsiasi dimensione del widget e viene riapplicato al ridimensionamento. Sui computer lenti la scena abbassa da sola risoluzione e bagliore.

T.vessel({ shape, radius, height })

Un contenitore di vetro ('jar', 'bowl', 'vase' o 'glass') visto da fuori e da dentro. fill(0..1, color) lo illumina verso un obiettivo.

T.orb({ image, radius, color })

Una biglia di vetro con un'immagine dentro (l'artwork di un regalo, un avatar): così un'immagine piatta diventa un oggetto 3D che può cadere e ammucchiarsi.

T.physics(stage) · world.add()

Fisica per oggetti rotondi: cadono, rimbalzano, rotolano, si ammucchiano in un contenitore e traboccano dal bordo. world.vessel(v), world.free(x, y, z, r), world.remove(body).

Materiali

Passane uno come material: … metalli, gemme e vetro, fumetto con toon shading (con contorno a inchiostro) e holo, rainbow e lava animati.

'gold''rosegold''silver''chrome''bronze''diamond''glass''ice''neon''plastic''candy''comic''holo''rainbow''lava'
Look

Post-processing per tutta la scena: comic ripassa i contorni a inchiostro e aggiunge i retini, retro aggiunge le scanline, cinematic fa la color correction dell'immagine.

'comic''retro''cinematic''none'
Effetti

Ognuno restituisce un handle: chiama stop(), kill() o remove() quando l'alert finisce.

T.fx.fireT.fx.lightningT.fx.sparksT.fx.shockwaveT.fx.comicBurstT.fx.speedLinesT.fx.confettiT.fx.shapesT.fx.rainT.fx.auraT.fx.embersT.fx.fogT.fx.rays
Nome 3D dorato con fuoco· il nome di ogni donatore in vere lettere 3D
var T, st;
TE.lib('three').then(function (lib) {
  T = lib;
  st = T.stage({ bloom: 0.6 });
  TE.on('gift', show);
  if (TE.demo) {
    var names = ['محمد الأسد', 'NightOwl', '𝓛𝓾𝓷𝓪'], i = 0;
    var next = function () { show({ user: { name: names[i++ % 3] } }); };
    next(); setInterval(next, 5000);
  }
});

async function show(ev) {
  var txt = await T.text3d(ev.user.name, { material: 'gold', maxWidth: 8, fallback: ev.user.username });
  st.add(txt); st.fit(Math.max(4, txt.userData.width + 1.5));
  txt.scale.setScalar(0.01); txt.rotation.y = -6;
  await T.animate(txt, { scale: 1, rotation: { y: 0 } }, { duration: 1100, ease: 'outBack' });
  var fire = T.fx.fire(st, { target: txt });
  T.fx.sparks(st, { at: { x: 0, y: 0, z: 0.5 }, count: 120 });
  var off = st.onFrame(function (dt, t) { txt.rotation.y = Math.sin(t) * 0.35; });
  await T.wait(2600);
  fire.kill(); off();
  await T.animate(txt, { scale: 0.01 }, { duration: 400, ease: 'inBack' });
  st.remove(txt);
}
Anteprima live
Regalo 3D di vetro· il regalo dentro una card di vetro, il nome in vetro luminoso
var T, st;
TE.lib('three').then(function (lib) {
  T = lib;
  st = T.stage({ bloom: 0.55 });
  TE.on('gift', show);
  if (TE.demo) {
    var rose = 'https://p16-webcast.tiktokcdn.com/img/maliva/webcast-va/eba3a9bb85c33e017f3648eaf88d7189~tplv-obj.png';
    var next = function () { show({ user: { name: 'NightOwl' }, gift: { image: rose } }); };
    next(); setInterval(next, 5000);
  }
});

async function show(ev) {
  var card = await T.panel({ width: 3, height: 3, tint: '#9fdcff', image: ev.gift.image });
  var name = await T.text3d(ev.user.name, { size: 0.8, material: 'glass', maxWidth: 7 });
  card.position.y = 1; name.position.y = -1.3;
  st.add(card); st.add(name); st.fit(8);
  card.rotation.y = -Math.PI; card.scale.setScalar(0.05);
  await T.animate(card, { rotation: { y: 0 }, scale: 1 }, { duration: 1000, ease: 'outBack' });
  var off = st.onFrame(function (dt, t) { card.rotation.y = Math.sin(t) * 0.35; });
  await T.wait(3000);
  off(); st.remove(card); st.remove(name);
}
Anteprima live
08

Sandbox e limiti

I widget girano in un iframe isolato con una content-security policy rigida, così un widget rotto o malevolo non può mai toccare il tuo account o il resto della pagina.

Consentito
  • Immagini e GIF remote (immagini dei regali TikTok, avatar, qualsiasi URL)
  • Google Fonts + i tuoi @font-face
  • Audio tramite new Audio(url)
  • Richieste alle API di TokElements (es. /api/files/…)
  • Animazioni CSS, SVG, canvas, Web Audio
  • 3D vero e modelli .glb caricati tramite TE.lib('three')
Bloccato
  • Tag <script> esterni / CDN
  • fetch / XHR / WebSocket verso altri host
  • Cookie, localStorage, accesso alla pagina principale
  • Caricare pacchetti npm
09

Esempi

Widget completi da copiare e incollare. Ogni anteprima è live: partono eventi demo così puoi vederla reagire.

Reazione alle emote· fa apparire l'emote quando viene inviata in chat
var img = document.getElementById('emote');
// fires for every emote — use TE.onSticker('<id>', …) for one specific one
TE.on('sticker', function (ev) {
  img.src = ev.url;
  img.classList.remove('show'); void img.offsetWidth; img.classList.add('show');
});
Anteprima live
Barra obiettivo follower· collega una barra a una metrica live
var target = 200;                       // ← your goal
TE.on('metrics', function (m) {
  var pct = Math.min(100, m.follows / target * 100);
  document.getElementById('fill').style.width = pct + '%';
  document.getElementById('txt').textContent = m.follows + ' / ' + target;
});
Anteprima live