Widget oluşturucu referansı

Bu sayfa, KickBot widget oluşturucu widget’larında kodunun kullanabileceği her şeyi listeler: widgetEvent olayları, globalValues nesnesi, userVariables nesnesi ve window.kickbotWidget yardımcıları. Her widget, OBS’de tarayıcı kaynağı olarak çalışan düz HTML, CSS ve JavaScript’tir. KickBot senin yerine Kick’e bağlanır ve olayları koduna gönderir.

Widget nasıl çalışır

OBS widget URL’sini açtığında KickBot:

1. Widget sayfasını şeffaf arka planla yükler.
2. CSS’ini bir <style> öğesine ekler ve HTML’ini sayfaya koyar.
3. Kanal verilerini Kick’ten (takipçi sayısı, izleyici sayısı, yayın durumu ve son chat mesajları) globalValues içine yükler.
4. JavaScript’ini çalıştırır. Kod 3. adımdan sonra bir kez çalışır, yani kodun başladığında globalValues hazırdır.
5. Canlı olayları koduna document üzerinde widgetEvent olayları olarak gönderir.

JavaScript’in hiçbir şey içe aktarmadan iki nesneyi okuyabilir: globalValues ve userVariables. Yardımcılar window.kickbotWidget üzerindedir.

Sınırlar:

Öğe	Sınır
Genişlik ve yükseklik	Temel ayarlar’dan belirlenir. Yeni boş widget 800 × 600’dür. Yeni widget penceresi en fazla 7680 × 4320 kabul eder.
HTML, CSS ve JavaScript	Dosya başına en fazla 2.000.000 karakter
Widget adı	En fazla 500 karakter
Kullanıcı değişkenleri için dosyalar	Dosya başına en fazla 25 MB
Ücretsiz planda oluşturucu widget’ları	10 (Premium’da sınır yok)

Olayları dinle

document üzerine widgetEvent için tek bir dinleyici ekle. Her olayda üç alanlı bir event.detail vardır:

Alan	Tür	Değer
event_name	string	Olay, örneğin followEvent
source	string	Her zaman kick
data	object	Olay verisi (aşağıya bak)

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

Olay listesi

Olay adı	Ne zaman tetiklenir	Test düğmesi
subEvent	Bir izleyici abone olur	Sub
subGiftEvent	Bir izleyici hediye abonelik verir	Hediye sub
kicksEvent	Bir izleyici KICKs gönderir	KICKs
followEvent	Bir izleyici takip eder	Follow
unfollowEvent	Bir izleyici takibi bırakır	Unfollow
chatMessageEvent	Bir chat mesajı gönderilir	Mesaj
chatMessageDeletedEvent	Bir moderatör mesaj siler	Mesaj silindi
chatMessagePinnedEvent	Bir mesaj sabitlenir	Mesaj sabitlendi
chatMessageUnpinnedEvent	Sabitlenen mesaj kaldırılır	Mesaj sabitlemesi kaldırıldı
chatClearedEvent	Bir moderatör chat’i temizler	Sohbet temizlendi
followerCountUpdatedEvent	Kick yeni bir takipçi sayısı gönderir	Follower sayısı güncellendi
subCountUpdatedEvent	Kick’teki abone sayısı değişir	Sub sayısı güncellendi
viewerCountUpdatedEvent	Kick yeni bir izleyici sayısı gönderir	İzleyici sayısı güncellendi
raidEvent	Başka bir kanal sana raid atar (host eder)	Raid
streamOnline	Yayının başlar	Yayın başladı
streamOffline	Yayının biter	Yayın kapandı

Bahşiş olayı yok. Bahşiş alertleri için bahşiş alerti widget’ını kullan.

Olay verileri

Bunlar event.detail.data içindeki verilerdir. Editördeki test olaylarıyla aynıdır. Gerçek olaylarda daha fazla alan olabilir. Buradaki adlar, sayılar ve ID’ler örnektir.

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 ve unfollowEvent (aynı yapı; followers_count yeni sayıdır)

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

Kick emote’ları content içinde [emote:ID:NAME] olarak gelir. Onları görsele çevirmek için createChatMessageFragment kullan (Chat metnini güvenle göster bölümüne bak).

chatMessageDeletedEvent

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

Gösterdiğin mesajı bulup kaldırmak için data.message.id kullan.

chatMessagePinnedEvent (data.message, chatMessageEvent verisiyle aynı yapıdadır)

{
    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 boş bir dizidir ([]).

chatClearedEvent

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

followerCountUpdatedEvent (camelCase yazılan followersCount’a dikkat et)

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

Genel değerler

globalValues, kanalının o anki durumunu tutar. KickBot onu kodun çalışmadan önce doldurur ve olaylar geldikçe güncel tutar. Widget’ını, daha hiçbir olay gelmeden en başta çizmek için kullan.

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

Değer	Nasıl güncellenir
subCount	Kick’ten yüklenir. Her subEvent için 1, her hediye abonelik için 1 artar ve subCountUpdatedEvent ile yeniden ayarlanır.
followerCount	Kick’ten yüklenir. followEvent, unfollowEvent ve followerCountUpdatedEvent ile ayarlanır.
viewerCount	Kick’ten yüklenir (yayında değilken 0). viewerCountUpdatedEvent ile ayarlanır.
lastFollower, lastSub, lastGiftedSub	KickBot’un kanalında gördüğü sonuncusu ya da null. İlgili olayla güncellenir.
chatMessages	Widget yüklendiğinde Kick’ten gelen son chat mesajları, sonra her yeni mesaj. En yeni 100 mesajı tutar. chatClearedEvent listeyi boşaltır. Silinen mesajları gizlemek için kendi kodunda chatMessageDeletedEvent’i işle.
streamerInfo.kick	Kick profilin. Widget çalışırken değişmez.
currentStream	Widget yüklendiğinde Kick’ten yüklenir. streamOnline veya streamOffline ile güncellenmez. Canlı durumu bilmen gerekiyorsa bu olayları dinle.

Kullanıcı değişkenleri

Kullanıcı değişkenleri, yayıncıların widget’ını Kayıtlı widget’larda açtığında gördüğü ayarlardır. Onları editörde Kullanıcı değişkenleri altında eklersin. Kodunda değeri userVariables.<variable name>.value ile oku.

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

Bir değişkenin alanları:

Alan	Ne işe yarar
Başlık	Yayıncıların gördüğü etiket.
Değişken adı	Kodundaki ad. Sadece harf, rakam ve _. Değişkeni oluşturduktan sonra değiştiremezsin.
Tooltip	Başlığın altındaki ek yardım metni.
Değişken türü	Aşağıdaki tabloya bak.
Varsayılan değer	Yayıncı değiştirmeden önceki değer. Boş olabilir.
Zorunlu	Yayıncılar kaydetmeden önce bir değer girmek zorundadır.

Tür	Yayıncının gördüğü	Kodundaki value
Metin	Bir metin kutusu	Bir string
Sayı	Bir sayı kutusu	Bir sayı veya sayısal bir string. Garanti olsun diye Number() kullan.
Renk	Bir renk seçici	Bir hex renk string’i, örneğin #ffffff
Açılır menü	Senin seçeneklerinin olduğu bir menü	Seçilen seçenek, string olarak. Varsayılan ilk seçenektir.
Anahtar	Bir aç/kapat anahtarı	true veya false
Görsel/GIF	Bir URL kutusu ve yükleme düğmesi	Dosyanın URL’si
Video	Bir URL kutusu ve yükleme düğmesi	Dosyanın URL’si
Ses	Bir URL kutusu ve yükleme düğmesi	Dosyanın URL’si

Yüklenen dosyaları KickBot saklar ve value dosyanın URL’sidir. Bir değişkeni yukarı veya aşağı taşımak, düzenlemek ya da silmek için yanındaki menüyü kullan. Editördeki sıra, yayıncıların gördüğü sıradır.

Chat metnini güvenle göster

Her olay alanını ve kullanıcı değişkenini bir yabancıdan gelen metin gibi düşün. KickBot chat ve olay metnini koduna ulaşmadan önce temizler. Bu yüzden HTML metni olarak güvenlidir ama URL, CSS veya script olarak değil. Ham olay alanlarını innerHTML içine koyma. Şu yardımcıları kullan:

Yardımcı	Ne yapar
window.kickbotWidget.createChatMessageFragment(content, font_size)	Metin düğümleri ve Kick emote görselleri içeren bir DocumentFragment döndürür. Emote’lar font_size + 3 piksel olur. font_size varsayılan olarak 20’dir.
window.kickbotWidget.createTextNode(value)	Herhangi bir değer için bir metin düğümü döndürür.
window.kickbotWidget.escapeHtmlText(value)	Mutlaka bir HTML string’i oluşturman gerektiğinde, metni HTML etiketleri arasında kullanmak için kaçışlar. URL, CSS veya script için kullanma.

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

Diğer metinler için textContent veya createTextNode kullan.

Önizleme

Editördeki önizleme OBS gibi çalışır, test için birkaç fark var:

• Kodu veya bir kullanıcı değişkenini değiştirdiğinde önizleme JavaScript’ini yeniden çalıştırır. KickBot önce bir önceki çalıştırmadan kalan widgetEvent dinleyicilerini kaldırır. setInterval ve setTimeout zamanlayıcıları kaldırılmaz, birikirlerse yenile düğmesine tıkla.
• Genişliği veya yüksekliği değiştirdiğinde önizleme yeniden yüklenir.
• Test olayları sadece önizlemeye gider. Test Follow olayı globalValues.followerCount değerine 1 ekler, Unfollow 1 çıkarır. İzleyici sayısı güncellendi örnek bir sayı gönderir. Mesaj silindi önizleme chat’inden rastgele bir mesajı kaldırır.
• Kanalında henüz son takipçi, abone veya hediye abonelik yoksa önizleme lastFollower, lastSub ve lastGiftedSub için örnek veri kullanır.
• console.log çıktısını ve hataları görmek için açılır pencere düğmesine tıkla ve o pencerede geliştirici araçlarını aç.

Örnek: takipçi hedefi

Bu kısa bir takipçi hedefi. Bir olay dinleyicisi, globalValues ve iki kullanıcı değişkeni kullanır: follower_goal (Sayı) ve bar_color (Renk).

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

Daha fazla ayarı olan tam sürüm için Simple Follower Goal şablonundan yeni bir widget başlat.

İpuçları

• İlk durumu globalValues’tan çiz, sonra olaylarda değiştir. Bir olay bekleyen widget, bir şey olana kadar boş görünür.
• Kayıtlı widget’lar sadece JavaScript’inde geçen olay adları için test düğmeleri gösterir. Yayıncılar widget’ını test edebilsin diye kodunda olay adının tamamını yaz (örneğin 'followEvent').
• Arka plan tasarımın bir parçası değilse şeffaf bırak, böylece widget sahnenin üstünde durur.
• Oluşturucu widget’larını KickBot API ile de yönetebilirsin. Widget API referansı sayfasına bak.