Référence de l'éditeur de widgets

Ouvrir dans le dashboard

Cette page liste ce que ton code peut utiliser dans un widget de l’éditeur de widgets KickBot : les événements widgetEvent, l’objet globalValues, l’objet userVariables et les helpers window.kickbotWidget. Chaque widget est du HTML, du CSS et du JavaScript classiques qui tournent comme source navigateur dans OBS. KickBot se connecte à Kick pour toi et envoie les événements à ton code.

Quand OBS ouvre l’URL du widget, KickBot :

Charge la page du widget avec un fond transparent.
Ajoute ton CSS dans un élément <style> et met ton HTML dans la page.
Charge les données de ta chaîne depuis Kick (nombre de followers, nombre de viewers, statut du stream et chat récent) dans globalValues.
Lance ton JavaScript. Il tourne une seule fois, après l’étape 3, donc globalValues est prêt quand ton code démarre.
Envoie les événements en direct à ton code sous forme d’événements widgetEvent sur document.

Ton JavaScript peut lire deux objets sans rien importer : globalValues et userVariables. Les helpers sont sur window.kickbotWidget.

Limites :

Élément	Limite
Largeur et hauteur	Réglées dans Paramètres de base. Un nouveau widget vide fait 800 × 600. La fenêtre Nouveau widget accepte jusqu’à 7680 × 4320.
HTML, CSS et JavaScript	Jusqu’à 2 000 000 caractères par fichier
Nom du widget	Jusqu’à 500 caractères
Fichiers des variables utilisateur	Jusqu’à 25 Mo par fichier
Widgets de l’éditeur avec le forfait Gratuit	10 (sans limite avec Premium)

Écoute les événements

Ajoute un seul listener pour widgetEvent sur document. Chaque événement contient event.detail avec trois champs :

Champ	Type	Valeur
`event_name`	string	L’événement, par exemple `followEvent`
`source`	string	Toujours `kick`
`data`	object	Les données de l’événement (voir plus bas)

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

Liste des événements

Nom de l’événement	Quand il se déclenche	Bouton de test
`subEvent`	Un viewer s’abonne	Sub
`subGiftEvent`	Un viewer offre des subs	Sub offert
`kicksEvent`	Un viewer envoie des KICKs	KICKs
`followEvent`	Un viewer follow	Follow
`unfollowEvent`	Un viewer unfollow	Unfollow
`chatMessageEvent`	Un message est envoyé dans le chat	Message
`chatMessageDeletedEvent`	Un modérateur supprime un message	Message supprimé
`chatMessagePinnedEvent`	Un message est épinglé	Message épinglé
`chatMessageUnpinnedEvent`	Le message épinglé est retiré	Message désépinglé
`chatClearedEvent`	Un modérateur efface le chat	Chat effacé
`followerCountUpdatedEvent`	Kick envoie un nouveau nombre de followers	Compteur de followers mis à jour
`subCountUpdatedEvent`	Le nombre de subs sur Kick a changé	Compteur de subs mis à jour
`viewerCountUpdatedEvent`	Kick envoie un nouveau nombre de viewers	Compteur de viewers mis à jour
`raidEvent`	Une autre chaîne te raid (host)	Raid
`streamOnline`	Ton stream commence	Stream en ligne
`streamOffline`	Ton stream se termine	Stream hors ligne

Il n’y a pas d’événement de tip. Pour les alertes de tip, utilise le widget d’alerte de tip.

Données des événements

Voici les données dans event.detail.data. Elles correspondent aux événements de test de l’éditeur. Les vrais événements peuvent avoir plus de champs. Les noms, nombres et ID ci-dessous sont des exemples.

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 et unfollowEvent (même forme ; followers_count est le nouveau nombre)

{
    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 }]
        }
    }
}

Les emotes Kick sont dans content sous la forme [emote:ID:NAME]. Utilise createChatMessageFragment (consulte Afficher le texte du chat en toute sécurité) pour les transformer en images.

chatMessageDeletedEvent

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

Utilise data.message.id pour retrouver et retirer le message que tu as affiché.

chatMessagePinnedEvent (data.message a la même forme que les données d’un 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 est un tableau vide ([]).

chatClearedEvent

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

followerCountUpdatedEvent (attention au camelCase 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 }
    }
}

Valeurs globales

globalValues contient l’état actuel de ta chaîne. KickBot le remplit avant que ton code tourne et le tient à jour quand les événements arrivent. Utilise-le pour dessiner ton widget au démarrage, avant l’arrivée du moindre événement.

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'
    }
}

Valeur	Comment elle se met à jour
`subCount`	Chargée depuis Kick. Augmente de 1 à chaque `subEvent` et de 1 pour chaque sub offert, et est remise à jour par `subCountUpdatedEvent`.
`followerCount`	Chargée depuis Kick. Mise à jour par `followEvent`, `unfollowEvent` et `followerCountUpdatedEvent`.
`viewerCount`	Chargée depuis Kick (0 hors ligne). Mise à jour par `viewerCountUpdatedEvent`.
`lastFollower`, `lastSub`, `lastGiftedSub`	Le dernier que KickBot a vu sur ta chaîne, ou `null`. Mis à jour par l’événement correspondant.
`chatMessages`	Le chat récent de Kick au chargement du widget, puis chaque nouveau message. Garde les 100 plus récents. `chatClearedEvent` le vide. Pour masquer les messages supprimés, gère `chatMessageDeletedEvent` dans ton propre code.
`streamerInfo.kick`	Ton profil Kick. Ne change pas pendant que le widget tourne.
`currentStream`	Chargée depuis Kick au chargement du widget. Elle n’est pas mise à jour par `streamOnline` ni `streamOffline`. Écoute ces événements si tu as besoin de l’état du live.

Variables utilisateur

Les variables utilisateur sont les paramètres que les streamers voient quand ils ouvrent ton widget dans Widgets enregistrés. Tu les ajoutes sous Variables utilisateur dans l’éditeur. Dans ton code, lis la valeur avec userVariables.<variable name>.value.

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

Champs d’une variable :

Champ	Ce que c’est
Titre	Le libellé que les streamers voient.
Nom de la variable	Le nom dans ton code. Lettres, chiffres et `_` uniquement. Tu ne peux plus le changer après avoir créé la variable.
Tooltip	Un texte d’aide en plus sous le titre.
Type de variable	Consulte le tableau ci-dessous.
Valeur par défaut	La valeur avant que le streamer la change. Elle peut être vide.
Obligatoire	Les streamers doivent saisir une valeur avant de pouvoir enregistrer.

Type	Ce que le streamer voit	`value` dans ton code
Texte	Un champ de texte	Une string
Nombre	Un champ de nombre	Un nombre ou une string numérique. Utilise `Number()` pour être sûr.
Couleur	Un sélecteur de couleur	Une couleur hexadécimale en string, par exemple `#ffffff`
Menu déroulant	Un menu avec tes options	L’option choisie, en string. Par défaut, c’est la première option.
Interrupteur	Un interrupteur on/off	`true` ou `false`
Image/GIF	Un champ d’URL et un bouton d’import	Une URL vers le fichier
Vidéo	Un champ d’URL et un bouton d’import	Une URL vers le fichier
Audio	Un champ d’URL et un bouton d’import	Une URL vers le fichier

Les fichiers importés sont stockés par KickBot, et value est l’URL du fichier. Utilise le menu à côté d’une variable pour la monter, la descendre, la modifier ou la supprimer. L’ordre dans l’éditeur est l’ordre que voient les streamers.

Afficher le texte du chat en toute sécurité

Traite chaque champ d’événement et chaque variable utilisateur comme du texte venant d’un inconnu. KickBot nettoie le texte du chat et des événements avant que ton code le reçoive, donc il est sûr comme texte HTML, mais pas comme URL, CSS ou script. Ne mets pas les champs bruts d’un événement dans innerHTML. Utilise ces helpers :

Helper	Ce qu’il fait
`window.kickbotWidget.createChatMessageFragment(content, font_size)`	Renvoie un `DocumentFragment` avec des nœuds texte et les images des emotes Kick. Les emotes font `font_size + 3` pixels. `font_size` vaut 20 par défaut.
`window.kickbotWidget.createTextNode(value)`	Renvoie un nœud texte pour n’importe quelle valeur.
`window.kickbotWidget.escapeHtmlText(value)`	Échappe le texte à placer entre des balises HTML quand tu dois construire une string HTML. Ne l’utilise pas pour des URL, du CSS ou du 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);
});

Pour les autres textes, utilise textContent ou createTextNode.

L’aperçu

L’aperçu de l’éditeur fonctionne comme OBS, avec quelques différences pour les tests :

Quand tu changes le code ou une variable utilisateur, l’aperçu relance ton JavaScript. KickBot retire d’abord les listeners widgetEvent du lancement précédent. Les minuteurs de setInterval et setTimeout ne sont pas retirés, donc clique sur le bouton de rechargement s’ils s’accumulent.
Quand tu changes la largeur ou la hauteur, l’aperçu se recharge.
Les événements de test vont seulement dans l’aperçu. Un Follow de test ajoute 1 à globalValues.followerCount, et Unfollow retire 1. Compteur de viewers mis à jour envoie un nombre d’exemple. Message supprimé retire un message au hasard du chat de l’aperçu.
Si ta chaîne n’a encore aucun dernier follower, sub ou sub offert, l’aperçu utilise des données d’exemple pour lastFollower, lastSub et lastGiftedSub.
Pour voir la sortie de console.log et les erreurs, clique sur le bouton qui ouvre l’aperçu dans une nouvelle fenêtre, puis ouvre les outils de développement dans cette fenêtre.

Exemple : objectif de followers

Voici un objectif de followers court. Il utilise un listener d’événements, globalValues et deux variables utilisateur : follower_goal (Nombre) et bar_color (Couleur).

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

Pour une version complète avec plus de paramètres, crée un nouveau widget à partir du modèle Simple Follower Goal.

Astuces

Dessine l’état de départ à partir de globalValues, puis change-le avec les événements. Un widget qui attend un événement reste vide tant que rien ne se passe.
Widgets enregistrés affiche seulement les boutons de test des noms d’événements présents dans ton JavaScript. Écris le nom complet de l’événement (par exemple 'followEvent') dans ton code pour que les streamers puissent tester ton widget.
Garde le fond transparent, sauf si un fond fait partie du design, pour que le widget se pose par-dessus la scène.
Tu peux aussi gérer les widgets de l’éditeur avec l’API KickBot. Consulte la référence de l’API des widgets.