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.
Primi passi
Le schede HTML e CSS disegnano il widget. Il riquadro è trasparente e sta sopra il video: non usare mai uno sfondo pieno e opaco.
Nella scheda JS iscriviti con TE.on('gift', fn). window.TE è già caricato: niente import, niente setup.
Usa Simulate o i pulsanti Fire per l'anteprima offline, poi Aggiungi all'overlay. Oppure lascia che lo crei Claude via MCP.
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');
});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.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 / allowGiftFiltri di idoneità riutilizzabili per ruoli, liste consentiti/bloccati, nome del regalo e valore minimo in monete.
TE.metricsL'ultimo snapshot della live (spettatori, like, monete, follower, topGifters…). Arriva anche tramite TE.on('metrics', fn).
TE.demoTrue 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.settingsL'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/incrementValori 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.
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 }] }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.
Azioni
Cosa può fare il tuo widget in risposta: normali API del browser, pronte da incollare.
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 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(); }
});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');
});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();
});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);
});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);
}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();
});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);
});
});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 });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);
});
});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);
});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 */ });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.
'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.
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).
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'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'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.raysvar 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);
}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);
}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.
- 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')
- Tag <script> esterni / CDN
- fetch / XHR / WebSocket verso altri host
- Cookie, localStorage, accesso alla pagina principale
- Caricare pacchetti npm
Esempi
Widget completi da copiare e incollare. Ogni anteprima è live: partono eventi demo così puoi vederla reagire.
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');
});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;
});