Riferimento del widget builder

Questa pagina elenca cosa può usare il tuo codice in un widget del widget builder di KickBot: gli eventi widgetEvent, l’oggetto globalValues, l’oggetto userVariables e gli helper di window.kickbotWidget. Ogni widget è semplice HTML, CSS e JavaScript che gira come fonte browser in OBS. KickBot si collega a Kick al posto tuo e invia gli eventi al tuo codice.

Come gira un widget

Quando OBS apre l’URL del widget, KickBot:

1. Carica la pagina del widget con lo sfondo trasparente.
2. Aggiunge il tuo CSS in un elemento <style> e inserisce il tuo HTML nella pagina.
3. Carica da Kick i dati del tuo canale (numero di follower, numero di spettatori, stato della live e chat recente) in globalValues.
4. Esegue il tuo JavaScript. Viene eseguito una volta, dopo il punto 3, quindi globalValues è pronto quando parte il tuo codice.
5. Invia gli eventi in tempo reale al tuo codice come eventi widgetEvent su document.

Il tuo JavaScript può leggere due oggetti senza importare nulla: globalValues e userVariables. Gli helper sono su window.kickbotWidget.

Limiti:

Elemento	Limite
Larghezza e altezza	Si impostano in Impostazioni di base. Un nuovo widget vuoto è 800 × 600. La finestra Nuovo widget accetta fino a 7680 × 4320.
HTML, CSS e JavaScript	Fino a 2.000.000 di caratteri per file
Nome del widget	Fino a 500 caratteri
File per le variabili utente	Fino a 25 MB per file
Widget del builder con il piano gratuito	10 (nessun limite con Premium)

Ascolta gli eventi

Aggiungi un listener per widgetEvent su document. Ogni evento ha event.detail con tre campi:

Campo	Tipo	Valore
event_name	string	L’evento, per esempio followEvent
source	string	Sempre kick
data	object	Il payload dell’evento (vedi sotto)

document.addEventListener('widgetEvent', (event) => {
    const { event_name, data } = event.detail;

    if (event_name === 'followEvent') {
        showAlert(data.user.username + ' followed!');
    }
    if (event_name === 'subEvent') {
        showAlert(data.username + ' subscribed for ' + data.months + ' months');
    }
});

Elenco degli eventi

Nome dell’evento	Quando parte	Pulsante di prova
subEvent	Uno spettatore si abbona	Sub
subGiftEvent	Uno spettatore regala dei sub	Sub regalato
kicksEvent	Uno spettatore invia dei KICKs	KICKs
followEvent	Uno spettatore inizia a seguirti	Follow
unfollowEvent	Uno spettatore smette di seguirti	Unfollow
chatMessageEvent	Viene inviato un messaggio in chat	Messaggio
chatMessageDeletedEvent	Un moderatore elimina un messaggio	Messaggio eliminato
chatMessagePinnedEvent	Un messaggio viene fissato	Messaggio fissato
chatMessageUnpinnedEvent	Il messaggio fissato viene rimosso	Messaggio non più fissato
chatClearedEvent	Un moderatore svuota la chat	Chat svuotata
followerCountUpdatedEvent	Kick invia un nuovo numero di follower	Numero di follower aggiornato
subCountUpdatedEvent	Il numero di sub su Kick è cambiato	Numero di sub aggiornato
viewerCountUpdatedEvent	Kick invia un nuovo numero di spettatori	Numero di spettatori aggiornato
raidEvent	Un altro canale ti fa un raid (host)	Raid
streamOnline	La tua live inizia	Live iniziata
streamOffline	La tua live finisce	Live terminata

Non esiste un evento per le donazioni. Per gli alert delle donazioni, usa il widget degli alert delle donazioni.

Payload degli eventi

Questi sono i payload in event.detail.data. Corrispondono agli eventi di prova dell’editor. Gli eventi reali possono avere più campi. Nomi, numeri e ID qui sono esempi.

subEvent

{
    months: 1,
    username: 'viewer_one',
    chatroom_id: 3847194
}

subGiftEvent

{
    chatroom_id: 3847194,
    gifted_usernames: ['viewer_one', 'viewer_two', 'viewer_three'],
    gifter_username: 'big_gifter'
}

kicksEvent

{
    message: 'Great stream!',
    sender: { id: 12345678, username: 'viewer_one', username_color: '#93EBE0' },
    gift: {
        gift_id: 'full_send',
        name: 'Full Send',
        amount: 100,
        type: 'BASIC',
        tier: 'BASIC',
        character_limit: 0,
        pinned_time: 0
    },
    channel: 'channel_3984507'
}

followEvent e unfollowEvent (stessa struttura; followers_count è il nuovo numero)

{
    id: 'd4e5f6a7-89b0-12c3-d456-78901e2f3a4b',
    channel: { id: 3984507, slug: 'kickbotdev' },
    user: { id: 14873539, slug: 'viewer_one', username: 'viewer_one' },
    followers_count: 36,
    created_at: '2024-05-13T22:19:07+00:00'
}

chatMessageEvent

{
    id: '85c884b3-7377-478c-b6aa-22b7db752b93',
    chatroom_id: 3974112,
    content: 'hello [emote:37226:KEKW]',
    type: 'message',
    created_at: '2024-05-13T22:29:52+00:00',
    sender: {
        id: 4063326,
        username: 'viewer_one',
        slug: 'viewer_one',
        identity: {
            color: '#72ACED',
            badges: [{ type: 'subscriber', text: 'Subscriber', count: 3 }]
        }
    }
}

Le emote di Kick sono in content come [emote:ID:NAME]. Usa createChatMessageFragment (vedi Mostra il testo della chat in modo sicuro) per trasformarle in immagini.

chatMessageDeletedEvent

{
    id: '9cd3788a-ecd2-4051-a162-a7ea9be8ce7a',
    message: { id: '89d6be86-63db-4581-922e-14a6c4a9c2e6' }
}

Usa data.message.id per trovare e rimuovere il messaggio che hai mostrato.

chatMessagePinnedEvent (data.message ha la stessa struttura del payload di chatMessageEvent)

{
    message: {
        id: '5d798a38-ad17-45e4-8169-bda2faa85b79',
        chatroom_id: 3974112,
        content: 'This is a pinned message!',
        type: 'message',
        created_at: '2024-05-13T22:30:41+00:00',
        sender: { id: 4063326, username: 'kickbotdev', slug: 'kickbotdev', identity: { color: '#72ACED', badges: [] } }
    }
}

chatMessageUnpinnedEvent: data è un array vuoto ([]).

chatClearedEvent

{ id: '47e3596f-0274-46e0-85b1-029fa3bfc5ea' }

followerCountUpdatedEvent (nota il camelCase di followersCount)

{ followersCount: 1532, channel_id: 4599, created_at: 1715639984 }

subCountUpdatedEvent

{ subscriber_count: 184, channel_id: 4599 }

viewerCountUpdatedEvent

{ viewer_count: 320, channel_id: 5937485 }

raidEvent

{
    chatroom_id: 839485,
    optional_message: 'gg stream',
    number_viewers: 150,
    host_username: 'raiding_channel'
}

streamOnline

{
    livestream: {
        id: 3984507,
        channel_id: 3984507,
        session_title: 'Test stream!',
        created_at: '2024-05-13T22:30:41+00:00'
    }
}

streamOffline

{
    livestream: {
        id: 3984507,
        channel: { id: 3984507, is_banned: false }
    }
}

Valori globali

globalValues contiene lo stato attuale del tuo canale. KickBot lo riempie prima che parta il tuo codice e lo tiene aggiornato man mano che arrivano gli eventi. Usalo per disegnare il widget all’inizio, prima che arrivi qualsiasi evento.

globalValues = {
    subCount: 184,
    followerCount: 1532,
    viewerCount: 320,
    lastFollower: { /* the last follow */ },
    lastSub: { /* the last sub, for example { username, months } */ },
    lastGiftedSub: { /* the last gift, for example { gifter_username, gifted_usernames } */ },
    chatMessages: [ /* chatMessageEvent payloads */ ],
    streamerInfo: {
        kick: {
            username: 'KickBotDev',
            slug: 'kickbotdev',
            profile_picture: 'https://files.kick.com/images/user/.../fullsize.webp',
            user_id: '4063326',
            channel_id: '3984507',
            chatroom_id: '3974112',
            bio: 'Channel bio',
            subscriber_badges: [ /* your channel's sub badges from Kick */ ]
        }
    },
    currentStream: {
        is_live: true,
        title: 'Stream title',
        started_at: '2026-10-24 18:00:00'
    }
}

Valore	Come si aggiorna
subCount	Caricato da Kick. Sale di 1 per ogni subEvent e di 1 per ogni sub regalato, e viene reimpostato da subCountUpdatedEvent.
followerCount	Caricato da Kick. Impostato da followEvent, unfollowEvent e followerCountUpdatedEvent.
viewerCount	Caricato da Kick (0 quando sei offline). Impostato da viewerCountUpdatedEvent.
lastFollower, lastSub, lastGiftedSub	L’ultimo che KickBot ha visto sul tuo canale, oppure null. Aggiornato dall’evento corrispondente.
chatMessages	La chat recente da Kick quando il widget si carica, poi ogni nuovo messaggio. Tiene i 100 più recenti. chatClearedEvent lo svuota. Per nascondere i messaggi eliminati, gestisci chatMessageDeletedEvent nel tuo codice.
streamerInfo.kick	Il tuo profilo Kick. Non cambia mentre il widget gira.
currentStream	Caricato da Kick quando il widget si carica. Non viene aggiornato da streamOnline né da streamOffline. Ascolta questi eventi se ti serve sapere se sei in live.

Variabili utente

Le variabili utente sono le impostazioni che gli streamer vedono quando aprono il tuo widget in Widget salvati. Le aggiungi in Variabili utente nell’editor. Nel tuo codice, leggi il valore con userVariables.<variable name>.value.

const goal = Number(userVariables.follower_goal.value);
document.body.style.color = userVariables.text_color.value;

Campi di una variabile:

Campo	Cos’è
Titolo	L’etichetta che vedono gli streamer.
Nome variabile	Il nome nel tuo codice. Solo lettere, numeri e _. Non puoi cambiarlo dopo aver creato la variabile.
Tooltip	Un testo di aiuto in più sotto il titolo.
Tipo di variabile	Vedi la tabella qui sotto.
Valore predefinito	Il valore prima che lo streamer lo cambi. Può essere vuoto.
Obbligatoria	Gli streamer devono inserire un valore prima di poter salvare.

Tipo	Cosa vede lo streamer	value nel tuo codice
Testo	Una casella di testo	Una stringa
Numero	Una casella per numeri	Un numero o una stringa numerica. Usa Number() per sicurezza.
Colore	Un selettore di colore	Una stringa con un colore esadecimale, per esempio #ffffff
Menu a tendina	Un menu con le tue opzioni	L’opzione scelta come stringa. Il predefinito è la prima opzione.
Interruttore	Un interruttore on/off	true o false
Immagine/GIF	Una casella per l’URL e un pulsante per caricare	Un URL del file
Video	Una casella per l’URL e un pulsante per caricare	Un URL del file
Audio	Una casella per l’URL e un pulsante per caricare	Un URL del file

I file caricati sono salvati da KickBot, e value è l’URL del file. Usa il menu accanto a una variabile per spostarla su o giù, modificarla o eliminarla. L’ordine nell’editor è l’ordine che vedono gli streamer.

Mostra il testo della chat in modo sicuro

Tratta ogni campo degli eventi e ogni variabile utente come testo scritto da uno sconosciuto. KickBot pulisce il testo della chat e degli eventi prima che arrivi al tuo codice, quindi è sicuro come testo HTML, ma non come URL, CSS o script. Non inserire i campi grezzi degli eventi in innerHTML. Usa questi helper:

Helper	Cosa fa
window.kickbotWidget.createChatMessageFragment(content, font_size)	Restituisce un DocumentFragment con nodi di testo e immagini delle emote di Kick. Le emote sono di font_size + 3 pixel. font_size vale 20 se non lo indichi.
window.kickbotWidget.createTextNode(value)	Restituisce un nodo di testo per qualsiasi valore.
window.kickbotWidget.escapeHtmlText(value)	Fa l’escape del testo da usare tra i tag HTML quando devi costruire una stringa HTML. Non usarlo per URL, CSS o script.

document.addEventListener('widgetEvent', (event) => {
    if (event.detail.event_name !== 'chatMessageEvent') return;
    const data = event.detail.data;

    const line = document.createElement('div');
    line.id = 'msg-' + data.id;
    const name = document.createElement('strong');
    name.style.color = data.sender.identity.color;
    name.append(window.kickbotWidget.createTextNode(data.sender.username + ': '));
    line.append(name);
    line.append(window.kickbotWidget.createChatMessageFragment(data.content, 20));
    document.getElementById('chat').append(line);
});

Per altro testo, usa textContent o createTextNode.

L’anteprima

L’anteprima nell’editor funziona come OBS, con qualche differenza per i test:

• Quando cambi il codice o una variabile utente, l’anteprima esegue di nuovo il tuo JavaScript. Prima KickBot rimuove i listener di widgetEvent dell’esecuzione precedente. I timer di setInterval e setTimeout non vengono rimossi, quindi clicca il pulsante di ricarica se si accumulano.
• Quando cambi larghezza o altezza, l’anteprima si ricarica.
• Gli eventi di prova arrivano solo all’anteprima. Un Follow di prova aggiunge 1 a globalValues.followerCount, e Unfollow toglie 1. Numero di spettatori aggiornato invia un numero di esempio. Messaggio eliminato rimuove un messaggio a caso dalla chat dell’anteprima.
• Se il tuo canale non ha ancora un ultimo follower, sub o sub regalato, l’anteprima usa dati di esempio per lastFollower, lastSub e lastGiftedSub.
• Per vedere l’output di console.log e gli errori, clicca il pulsante per aprire l’anteprima in una finestra separata e apri gli strumenti per sviluppatori in quella finestra.

Esempio: obiettivo follower

Questo è un breve obiettivo follower. Usa un listener di eventi, globalValues e due variabili utente: follower_goal (Numero) e bar_color (Colore).

HTML:

<div class="goal">
    <span id="count"></span> / <span id="target"></span>
    <div class="bar"><div class="fill"></div></div>
</div>

CSS:

body { margin: 0; font-family: Arial, sans-serif; color: #fff; }
.goal { padding: 12px; background: #100c28; border-radius: 16px; font-size: 32px; font-weight: bold; }
.bar { height: 24px; margin-top: 8px; background: #3d3957; border-radius: 12px; overflow: hidden; }
.fill { height: 100%; width: 0; transition: width 0.3s ease; }

JavaScript:

const target = Number(userVariables.follower_goal.value) || 100;
document.getElementById('target').textContent = target;
document.querySelector('.fill').style.background = userVariables.bar_color.value;

function update(count) {
    document.getElementById('count').textContent = count;
    document.querySelector('.fill').style.width = Math.min((count / target) * 100, 100) + '%';
}

document.addEventListener('widgetEvent', (event) => {
    const { event_name, data } = event.detail;
    if (event_name === 'followEvent' || event_name === 'unfollowEvent') update(data.followers_count);
    if (event_name === 'followerCountUpdatedEvent') update(data.followersCount);
});

update(globalValues.followerCount);

Per una versione completa con più impostazioni, crea un nuovo widget dal modello Simple Follower Goal.

Consigli

• Disegna lo stato iniziale da globalValues, poi cambialo con gli eventi. Un widget che aspetta un evento resta vuoto finché non succede qualcosa.
• Widget salvati mostra i pulsanti di prova solo per i nomi degli eventi che compaiono nel tuo JavaScript. Scrivi il nome completo dell’evento (per esempio 'followEvent') nel tuo codice, così gli streamer possono provare il tuo widget.
• Tieni lo sfondo trasparente, a meno che uno sfondo non faccia parte del design, così il widget sta sopra la scena.
• Puoi anche gestire i widget del builder con l’API di KickBot. Vedi il riferimento API dei widget.