# विजेट बिल्डर रेफ़रेंस (इवेंट्स और डेटा)

> KickBot विजेट बिल्डर के विजेट के लिए कोड रेफ़रेंस: हर Kick इवेंट का नाम और पेलोड, globalValues, userVariables, चैट हेल्पर और प्रीव्यू में कोड कैसे चलता है।

Source: https://kickbot.com/hi/docs/widgets/widget-builder-reference

इस पेज पर वह सब है जो आपका कोड KickBot [विजेट बिल्डर](https://kickbot.com/hi/docs/widgets/widget-builder) के विजेट में इस्तेमाल कर सकता है: `widgetEvent` इवेंट्स, `globalValues` ऑब्जेक्ट, `userVariables` ऑब्जेक्ट, और `window.kickbotWidget` हेल्पर। हर विजेट सामान्य HTML, CSS और JavaScript है, जो OBS में ब्राउज़र सोर्स के रूप में चलता है। KickBot आपके लिए Kick से कनेक्ट करता है और इवेंट्स आपके कोड तक भेजता है।

## विजेट कैसे चलता है

जब OBS विजेट का URL खोलता है, तो KickBot:

1. पारदर्शी बैकग्राउंड के साथ विजेट पेज लोड करता है।
2. आपका CSS एक `<style>` एलिमेंट में जोड़ता है और आपका HTML पेज में डालता है।
3. Kick से आपके चैनल का डेटा (फ़ॉलोअर्स की संख्या, दर्शकों की संख्या, स्ट्रीम का स्टेटस और हाल की चैट) `globalValues` में लोड करता है।
4. आपका JavaScript चलाता है। यह स्टेप 3 के बाद एक बार चलता है, इसलिए आपका कोड शुरू होते समय `globalValues` तैयार होता है।
5. लाइव इवेंट्स को `document` पर `widgetEvent` इवेंट्स के रूप में आपके कोड तक भेजता है।

आपका JavaScript बिना कुछ इंपोर्ट किए दो ऑब्जेक्ट पढ़ सकता है: `globalValues` और `userVariables`। हेल्पर `window.kickbotWidget` पर हैं।

लिमिट:

| चीज़ | लिमिट |
| --- | --- |
| चौड़ाई और ऊँचाई | **बेसिक सेटिंग्स** में सेट होती है। नया खाली विजेट 800 × 600 का होता है। नया विजेट पॉपअप 7680 × 4320 तक लेता है। |
| HTML, CSS और JavaScript | हर फ़ाइल में 2,000,000 कैरेक्टर तक |
| विजेट का नाम | 500 कैरेक्टर तक |
| यूज़र वेरिएबल की फ़ाइलें | हर फ़ाइल 25 MB तक |
| फ़्री प्लान पर बिल्डर विजेट | 10 (Premium पर कोई लिमिट नहीं) |

## इवेंट्स सुनें

`document` पर `widgetEvent` के लिए एक लिसनर जोड़ें। हर इवेंट में `event.detail` होता है, जिसमें तीन फ़ील्ड होते हैं:

| फ़ील्ड | टाइप | वैल्यू |
| --- | --- | --- |
| `event_name` | string | इवेंट, जैसे `followEvent` |
| `source` | string | हमेशा `kick` |
| `data` | object | इवेंट का पेलोड (नीचे देखें) |

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

### इवेंट्स की लिस्ट

| इवेंट का नाम | कब चलता है | टेस्ट बटन |
| --- | --- | --- |
| `subEvent` | कोई दर्शक सब्सक्राइब करता है | सब |
| `subGiftEvent` | कोई दर्शक सब्स गिफ़्ट करता है | गिफ़्टेड सब |
| `kicksEvent` | कोई दर्शक KICKs भेजता है | KICKs |
| `followEvent` | कोई दर्शक फ़ॉलो करता है | फ़ॉलो |
| `unfollowEvent` | कोई दर्शक अनफ़ॉलो करता है | अनफ़ॉलो |
| `chatMessageEvent` | चैट में कोई मैसेज भेजा जाता है | मैसेज |
| `chatMessageDeletedEvent` | कोई मॉडरेटर मैसेज हटाता है | मैसेज हटाया गया |
| `chatMessagePinnedEvent` | कोई मैसेज पिन होता है | मैसेज पिन |
| `chatMessageUnpinnedEvent` | पिन किया मैसेज हटाया जाता है | मैसेज अनपिन |
| `chatClearedEvent` | कोई मॉडरेटर चैट साफ़ करता है | चैट साफ़ की गई |
| `followerCountUpdatedEvent` | Kick फ़ॉलोअर्स की नई संख्या भेजता है | फ़ॉलोअर काउंट अपडेट हुआ |
| `subCountUpdatedEvent` | Kick पर सब्स की संख्या बदली | सब काउंट अपडेट हुआ |
| `viewerCountUpdatedEvent` | Kick दर्शकों की नई संख्या भेजता है | दर्शकों की संख्या अपडेट हुई |
| `raidEvent` | कोई दूसरा चैनल आप पर रेड (होस्ट) करता है | रेड |
| `streamOnline` | आपकी स्ट्रीम शुरू होती है | स्ट्रीम ऑनलाइन |
| `streamOffline` | आपकी स्ट्रीम खत्म होती है | स्ट्रीम ऑफ़लाइन |

टिप का कोई इवेंट नहीं है। टिप अलर्ट के लिए [टिप अलर्ट विजेट](https://kickbot.com/hi/docs/tipping/tip-alerts) इस्तेमाल करें।

### इवेंट पेलोड

ये `event.detail.data` में आने वाले पेलोड हैं। ये एडिटर के टेस्ट इवेंट्स से मेल खाते हैं। असली इवेंट्स में और फ़ील्ड भी हो सकते हैं। यहाँ के नाम, नंबर और ID सिर्फ़ उदाहरण हैं।

`subEvent`

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

`subGiftEvent`

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

`kicksEvent`

```javascript
{
    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` और `unfollowEvent` (बनावट एक जैसी; `followers_count` नई संख्या है)

```javascript
{
    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`

```javascript
{
    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 इमोट `content` में `[emote:ID:NAME]` के रूप में होते हैं। उन्हें इमेज में बदलने के लिए `createChatMessageFragment` इस्तेमाल करें (देखें [चैट टेक्स्ट सुरक्षित तरीके से दिखाएँ](#show-chat-text-safely))।

`chatMessageDeletedEvent`

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

आपने जो मैसेज दिखाया था, उसे ढूँढकर हटाने के लिए `data.message.id` इस्तेमाल करें।

`chatMessagePinnedEvent` (`data.message` की बनावट `chatMessageEvent` पेलोड जैसी ही है)

```javascript
{
    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` एक खाली array (`[]`) है।

`chatClearedEvent`

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

`followerCountUpdatedEvent` (ध्यान दें: camelCase में `followersCount`)

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

`subCountUpdatedEvent`

```javascript
{ subscriber_count: 184, channel_id: 4599 }
```

`viewerCountUpdatedEvent`

```javascript
{ viewer_count: 320, channel_id: 5937485 }
```

`raidEvent`

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

`streamOnline`

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

`streamOffline`

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

## ग्लोबल वैल्यू

`globalValues` में आपके चैनल की मौजूदा स्थिति होती है। KickBot आपका कोड चलने से पहले इसे भर देता है, और इवेंट्स आने पर इसे अपडेट रखता है। किसी इवेंट के आने से पहले, शुरू में ही अपना विजेट बनाने के लिए इसे इस्तेमाल करें।

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

| वैल्यू | कैसे अपडेट होती है |
| --- | --- |
| `subCount` | Kick से लोड होती है। हर `subEvent` पर और हर गिफ़्टेड सब पर 1 बढ़ती है, और `subCountUpdatedEvent` इसे फिर से सेट करता है। |
| `followerCount` | Kick से लोड होती है। `followEvent`, `unfollowEvent` और `followerCountUpdatedEvent` इसे सेट करते हैं। |
| `viewerCount` | Kick से लोड होती है (ऑफ़लाइन होने पर 0)। `viewerCountUpdatedEvent` इसे सेट करता है। |
| `lastFollower`, `lastSub`, `lastGiftedSub` | आपके चैनल पर KickBot का देखा हुआ आखिरी फ़ॉलो, सब या गिफ़्ट, या `null`। उससे मेल खाने वाला इवेंट इसे अपडेट करता है। |
| `chatMessages` | विजेट लोड होने पर Kick से हाल की चैट, फिर हर नया मैसेज। सबसे नए 100 मैसेज रखती है। `chatClearedEvent` इसे खाली कर देता है। हटाए गए मैसेज छिपाने के लिए अपने कोड में `chatMessageDeletedEvent` को हैंडल करें। |
| `streamerInfo.kick` | आपकी Kick प्रोफ़ाइल। विजेट चलते समय यह नहीं बदलती। |
| `currentStream` | विजेट लोड होने पर Kick से लोड होती है। `streamOnline` या `streamOffline` इसे अपडेट नहीं करते। अगर आपको लाइव स्थिति चाहिए, तो इन इवेंट्स को सुनें। |

## यूज़र वेरिएबल

यूज़र वेरिएबल वे सेटिंग्स हैं, जो स्ट्रीमर्स को तब दिखती हैं जब वे सेव किए विजेट में आपका विजेट खोलते हैं। आप इन्हें एडिटर में **यूज़र वेरिएबल** में जोड़ते हैं। अपने कोड में वैल्यू `userVariables.<variable name>.value` से पढ़ें।

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

वेरिएबल के फ़ील्ड:

| फ़ील्ड | यह क्या है |
| --- | --- |
| टाइटल | वह लेबल जो स्ट्रीमर्स को दिखता है। |
| वेरिएबल का नाम | आपके कोड में इस्तेमाल होने वाला नाम। सिर्फ़ अक्षर, नंबर और `_`। वेरिएबल बनाने के बाद आप इसे बदल नहीं सकते। |
| टूलटिप | टाइटल के नीचे मदद के लिए एक्स्ट्रा टेक्स्ट। |
| वेरिएबल टाइप | नीचे की टेबल देखें। |
| डिफ़ॉल्ट वैल्यू | स्ट्रीमर के बदलने से पहले की वैल्यू। यह खाली भी हो सकती है। |
| ज़रूरी | सेव करने से पहले स्ट्रीमर्स को कोई वैल्यू डालनी होगी। |

| टाइप | स्ट्रीमर को क्या दिखता है | आपके कोड में `value` |
| --- | --- | --- |
| टेक्स्ट | एक टेक्स्ट बॉक्स | एक string |
| नंबर | एक नंबर बॉक्स | एक number या नंबर वाली string। सुरक्षित रहने के लिए `Number()` इस्तेमाल करें। |
| रंग | एक कलर पिकर | hex रंग की string, जैसे `#ffffff` |
| ड्रॉपडाउन | आपके विकल्पों वाला मेन्यू | चुना गया विकल्प, string के रूप में। डिफ़ॉल्ट पहला विकल्प है। |
| टॉगल | चालू/बंद स्विच | `true` या `false` |
| इमेज/GIF | एक URL बॉक्स और अपलोड बटन | फ़ाइल का URL |
| वीडियो | एक URL बॉक्स और अपलोड बटन | फ़ाइल का URL |
| ऑडियो | एक URL बॉक्स और अपलोड बटन | फ़ाइल का URL |

अपलोड की गई फ़ाइलें KickBot स्टोर करता है, और `value` फ़ाइल का URL होता है। किसी वेरिएबल को ऊपर या नीचे ले जाने, एडिट करने या हटाने के लिए उसके बगल वाला मेन्यू इस्तेमाल करें। एडिटर में जो क्रम है, स्ट्रीमर्स को वही क्रम दिखता है।

## चैट टेक्स्ट सुरक्षित तरीके से दिखाएँ

हर इवेंट फ़ील्ड और यूज़र वेरिएबल को किसी अनजान व्यक्ति का टेक्स्ट मानें। आपके कोड तक पहुँचने से पहले KickBot चैट और इवेंट का टेक्स्ट साफ़ कर देता है, इसलिए वह HTML टेक्स्ट के रूप में सुरक्षित है, लेकिन URL, CSS या स्क्रिप्ट के रूप में नहीं। इवेंट के कच्चे फ़ील्ड `innerHTML` में न डालें। ये हेल्पर इस्तेमाल करें:

| हेल्पर | क्या करता है |
| --- | --- |
| `window.kickbotWidget.createChatMessageFragment(content, font_size)` | टेक्स्ट नोड और Kick इमोट इमेज वाला एक `DocumentFragment` लौटाता है। इमोट `font_size + 3` पिक्सेल के होते हैं। `font_size` डिफ़ॉल्ट रूप से 20 है। |
| `window.kickbotWidget.createTextNode(value)` | किसी भी वैल्यू के लिए एक टेक्स्ट नोड लौटाता है। |
| `window.kickbotWidget.escapeHtmlText(value)` | जब आपको HTML string बनानी ही हो, तब HTML टैग के बीच इस्तेमाल के लिए टेक्स्ट को escape करता है। इसे URL, CSS या स्क्रिप्ट के लिए इस्तेमाल न करें। |

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

दूसरे टेक्स्ट के लिए `textContent` या `createTextNode` इस्तेमाल करें।

## प्रीव्यू

एडिटर का प्रीव्यू OBS की तरह ही काम करता है, बस टेस्टिंग के लिए कुछ फ़र्क हैं:

- जब आप कोड या कोई यूज़र वेरिएबल बदलते हैं, तो प्रीव्यू आपका JavaScript फिर से चलाता है। KickBot पहले पिछली बार के `widgetEvent` लिसनर हटा देता है। `setInterval` और `setTimeout` के टाइमर नहीं हटते, इसलिए अगर वे जमा हो जाएँ, तो रीलोड बटन पर क्लिक करें।
- जब आप चौड़ाई या ऊँचाई बदलते हैं, तो प्रीव्यू रीलोड होता है।
- टेस्ट इवेंट्स सिर्फ़ प्रीव्यू में जाते हैं। टेस्ट **फ़ॉलो** `globalValues.followerCount` में 1 जोड़ता है, और **अनफ़ॉलो** 1 घटाता है। **दर्शकों की संख्या अपडेट हुई** एक सैंपल संख्या भेजता है। **मैसेज हटाया गया** प्रीव्यू चैट से कोई भी एक मैसेज हटा देता है।
- अगर आपके चैनल पर अभी तक कोई आखिरी फ़ॉलोअर, सब या गिफ़्टेड सब नहीं है, तो प्रीव्यू `lastFollower`, `lastSub` और `lastGiftedSub` के लिए सैंपल डेटा इस्तेमाल करता है।
- `console.log` का आउटपुट और एरर देखने के लिए पॉप-आउट बटन पर क्लिक करें और उस विंडो में डेवलपर टूल्स खोलें।

## उदाहरण: फ़ॉलोअर लक्ष्य

यह एक छोटा फ़ॉलोअर लक्ष्य है। इसमें एक इवेंट लिसनर, `globalValues` और दो यूज़र वेरिएबल इस्तेमाल होते हैं: `follower_goal` (नंबर) और `bar_color` (रंग)।

HTML:

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

CSS:

```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:

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

ज़्यादा सेटिंग्स वाले पूरे वर्ज़न के लिए **Simple Follower Goal** टेम्पलेट से नया विजेट शुरू करें।

## काम के सुझाव

- पहली स्थिति `globalValues` से बनाएँ, फिर इवेंट्स आने पर उसे बदलें। जो विजेट किसी इवेंट का इंतज़ार करता है, वह कुछ होने तक खाली दिखता है।
- सेव किए विजेट सिर्फ़ उन इवेंट नामों के टेस्ट बटन दिखाता है, जो आपके JavaScript में हैं। अपने कोड में इवेंट का पूरा नाम (जैसे `'followEvent'`) लिखें, ताकि स्ट्रीमर्स आपका विजेट टेस्ट कर सकें।
- बैकग्राउंड पारदर्शी रखें, जब तक बैकग्राउंड डिज़ाइन का हिस्सा न हो, ताकि विजेट सीन के ऊपर दिखे।
- आप KickBot API से भी बिल्डर विजेट मैनेज कर सकते हैं। देखें [विजेट API रेफ़रेंस](https://kickbot.com/docs/api/reference/widgets)।