Reference Tvůrce widgetů

Otevřít v dashboardu

Tato stránka popisuje, co může tvůj kód používat ve widgetu z Tvůrce widgetů KickBotu: události widgetEvent, objekt globalValues, objekt userVariables a pomocníky window.kickbotWidget. Každý widget je obyčejné HTML, CSS a JavaScript, které v OBS běží jako zdroj prohlížeče. KickBot se za tebe připojí ke Kicku a posílá události do tvého kódu.

Když OBS otevře URL widgetu, KickBot:

Načte stránku widgetu s průhledným pozadím.
Vloží tvoje CSS do prvku <style> a tvoje HTML do stránky.
Načte z Kicku data tvého kanálu (počet sledujících, počet diváků, stav streamu a nedávný chat) do globalValues.
Spustí tvůj JavaScript. Ten běží jednou, po kroku 3, takže globalValues je připravený, když tvůj kód startuje.
Posílá do tvého kódu živé události jako události widgetEvent na document.

Tvůj JavaScript může bez jakéhokoli importu číst dva objekty: globalValues a userVariables. Pomocníci jsou na window.kickbotWidget.

Limity:

Položka	Limit
Šířka a výška	Nastavuje se v Základním nastavení. Nový prázdný widget má 800 × 600. Okno Nový widget přijme až 7680 × 4320.
HTML, CSS a JavaScript	Až 2 000 000 znaků na soubor
Název widgetu	Až 500 znaků
Soubory pro uživatelské proměnné	Až 25 MB na soubor
Widgety z Tvůrce v tarifu zdarma	10 (s Premium bez limitu)

Poslouchej události

Přidej na document jeden posluchač pro widgetEvent. Každá událost má event.detail se třemi poli:

Pole	Typ	Hodnota
`event_name`	string	Událost, třeba `followEvent`
`source`	string	Vždy `kick`
`data`	object	Data události (viz níže)

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

Seznam událostí

Název události	Kdy nastane	Testovací tlačítko
`subEvent`	Divák si předplatí kanál	Sub
`subGiftEvent`	Divák daruje suby	Darovaný sub
`kicksEvent`	Divák pošle KICKs	KICKs
`followEvent`	Divák začne sledovat	Sledování
`unfollowEvent`	Divák přestane sledovat	Zrušení sledování
`chatMessageEvent`	Někdo pošle zprávu do chatu	Zpráva
`chatMessageDeletedEvent`	Moderátor smaže zprávu	Zpráva smazána
`chatMessagePinnedEvent`	Zpráva se připne	Připnutí zprávy
`chatMessageUnpinnedEvent`	Připnutá zpráva se odepne	Odepnutí zprávy
`chatClearedEvent`	Moderátor vymaže chat	Chat vymazán
`followerCountUpdatedEvent`	Kick pošle nový počet sledujících	Změna počtu sledujících
`subCountUpdatedEvent`	Počet subů na Kicku se změnil	Změna počtu subů
`viewerCountUpdatedEvent`	Kick pošle nový počet diváků	Změna počtu diváků
`raidEvent`	Jiný kanál tě raiduje (hostuje)	Raid
`streamOnline`	Tvůj stream začne	Stream začal
`streamOffline`	Tvůj stream skončí	Stream skončil

Událost pro donate neexistuje. Na alerty na donaty použij widget s alertem na donate.

Data událostí

Toto jsou data v event.detail.data. Odpovídají testovacím událostem v editoru. Skutečné události můžou mít víc polí. Jména, čísla a ID jsou tu jen příklady.

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 a unfollowEvent (stejný tvar; followers_count je nový počet)

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

Emoty z Kicku jsou v content jako [emote:ID:NAME]. Na obrázky je převedeš pomocí createChatMessageFragment (viz Bezpečné zobrazení textu z chatu).

chatMessageDeletedEvent

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

Podle data.message.id najdeš a odstraníš zprávu, kterou widget ukazuje.

chatMessagePinnedEvent (data.message má stejný tvar jako data 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 je prázdné pole ([]).

chatClearedEvent

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

followerCountUpdatedEvent (pozor na 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 }
    }
}

Globální hodnoty

globalValues obsahuje aktuální stav tvého kanálu. KickBot ho naplní, než se tvůj kód spustí, a s každou příchozí událostí ho aktualizuje. Použij ho k vykreslení widgetu hned na začátku, ještě před první událostí.

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

Hodnota	Jak se aktualizuje
`subCount`	Načte se z Kicku. S každým `subEvent` a s každým darovaným subem se zvýší o 1 a `subCountUpdatedEvent` ho nastaví znovu.
`followerCount`	Načte se z Kicku. Nastavují ho `followEvent`, `unfollowEvent` a `followerCountUpdatedEvent`.
`viewerCount`	Načte se z Kicku (0, když nestreamuješ). Nastavuje ho `viewerCountUpdatedEvent`.
`lastFollower`, `lastSub`, `lastGiftedSub`	Poslední, kterého KickBot na tvém kanálu zaznamenal, nebo `null`. Aktualizuje ho příslušná událost.
`chatMessages`	Nedávný chat z Kicku při načtení widgetu, pak každá nová zpráva. Drží 100 nejnovějších. `chatClearedEvent` ho vyprázdní. Pokud chceš skrýt smazané zprávy, zpracuj `chatMessageDeletedEvent` ve vlastním kódu.
`streamerInfo.kick`	Tvůj profil na Kicku. Během běhu widgetu se nemění.
`currentStream`	Načte se z Kicku při načtení widgetu. `streamOnline` ani `streamOffline` ho neaktualizují. Pokud potřebuješ aktuální stav, poslouchej tyto události.

Uživatelské proměnné

Uživatelské proměnné jsou nastavení, která streameři vidí, když tvůj widget otevřou v Uložených widgetech. Přidáváš je v editoru v části Uživatelské proměnné. V kódu hodnotu přečteš přes userVariables.<variable name>.value.

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

Pole proměnné:

Pole	Co to je
Titulek	Popisek, který streameři vidí.
Název proměnné	Název v tvém kódu. Jen písmena, čísla a `_`. Po vytvoření proměnné ho už nezměníš.
Nápověda	Doplňující text pod titulkem.
Typ proměnné	Viz tabulku níže.
Výchozí hodnota	Hodnota, než ji streamer změní. Může být prázdná.
Povinné	Streameři musí zadat hodnotu, než můžou uložit.

Typ	Co streamer vidí	`value` v tvém kódu
Text	Textové pole	String
Číslo	Pole na číslo	Číslo nebo číselný string. Pro jistotu použij `Number()`.
Barva	Výběr barvy	Barva jako hex string, třeba `#ffffff`
Rozbalovací nabídka	Nabídka s tvými možnostmi	Vybraná možnost jako string. Výchozí je první možnost.
Přepínač	Vypínač zapnuto/vypnuto	`true` nebo `false`
Obrázek/GIF	Pole na URL a tlačítko pro nahrání	URL souboru
Video	Pole na URL a tlačítko pro nahrání	URL souboru
Zvuk	Pole na URL a tlačítko pro nahrání	URL souboru

Nahrané soubory ukládá KickBot a value je URL souboru. Nabídkou vedle proměnné ji posuneš nahoru nebo dolů, upravíš nebo smažeš. Pořadí v editoru je stejné pořadí, jaké vidí streameři.

Bezpečné zobrazení textu z chatu

Každé pole události a každou uživatelskou proměnnou ber jako text od cizího člověka. KickBot text z chatu a z událostí vyčistí dřív, než ho tvůj kód dostane, takže je bezpečný jako text v HTML, ale ne jako URL, CSS nebo skript. Nevkládej surová pole událostí do innerHTML. Použij tyto pomocníky:

Pomocník	Co dělá
`window.kickbotWidget.createChatMessageFragment(content, font_size)`	Vrátí `DocumentFragment` s textovými uzly a obrázky emotů z Kicku. Emoty mají `font_size + 3` pixelů. Výchozí `font_size` je 20.
`window.kickbotWidget.createTextNode(value)`	Vrátí textový uzel pro jakoukoli hodnotu.
`window.kickbotWidget.escapeHtmlText(value)`	Escapuje text pro použití mezi HTML tagy, když musíš sestavit HTML string. Nepoužívej ho pro URL, CSS ani skripty.

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

Pro jiný text použij textContent nebo createTextNode.

Náhled

Náhled v editoru funguje jako OBS, jen s několika rozdíly kvůli testování:

Když změníš kód nebo uživatelskou proměnnou, náhled spustí tvůj JavaScript znovu. KickBot nejdřív odebere posluchače widgetEvent z předchozího běhu. Časovače z setInterval a setTimeout se neodebírají, takže když se nahromadí, klikni na tlačítko pro znovunačtení.
Když změníš šířku nebo výšku, náhled se načte znovu.
Testovací události jdou jen do náhledu. Testovací Sledování přičte 1 k globalValues.followerCount a Zrušení sledování 1 odečte. Změna počtu diváků pošle ukázkové číslo. Zpráva smazána odstraní náhodnou zprávu z chatu v náhledu.
Pokud tvůj kanál ještě nemá posledního sledujícího, sub ani darovaný sub, náhled použije pro lastFollower, lastSub a lastGiftedSub ukázková data.
Výstup console.log a chyby uvidíš, když klikneš na tlačítko pro vyskakovací okno a v tom okně otevřeš nástroje pro vývojáře.

Příklad: cíl sledujících

Tohle je krátký cíl sledujících. Používá posluchač událostí, globalValues a dvě uživatelské proměnné: follower_goal (Číslo) a bar_color (Barva).

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

Plnou verzi s dalšími nastaveními dostaneš, když založíš nový widget ze šablony Simple Follower Goal.

Tipy

Výchozí stav vykresli z globalValues a při událostech ho měň. Widget, který čeká na událost, je prázdný, dokud se něco nestane.
Uložené widgety ukazují testovací tlačítka jen pro názvy událostí, které se objeví v tvém JavaScriptu. Do kódu piš celý název události (třeba 'followEvent'), aby streameři mohli tvůj widget otestovat.
Nech pozadí průhledné, pokud pozadí není součástí designu. Widget pak leží nad scénou.
Widgety z Tvůrce můžeš spravovat i přes API KickBotu. Viz Reference API pro widgety.