Livedeck widget SDK: functions और events
livedeck object जो कुछ करता है: events, settings, तस्वीरें, sounds और context।
SDK एक छोटी library है जिसे Livedeck हर widget के पते पर /sdk/v1.js के तहत देता है। यह आपके widget को overlay से जोड़ती है और livedeck object देती है।
<script src="/sdk/v1.js"></script>इसे अपने code से पहले load करें। पेज load होते ही SDK खुद overlay को सूचना देता है। इसके लिए आपको कुछ भी call करने की ज़रूरत नहीं है।
Functions
livedeck.on(type, fn)
इस type के हर event पर fn को call करता है। एक function लौटाता है जो fn को फिर से हटा देता है।
livedeck.off(type, fn)
fn को हटाता है।
livedeck.ready(fn)
overlay connect होते ही और settings आते ही fn को call करता है। एक Promise भी लौटाता है।
livedeck.settings
मौजूदा settings (read-only)। जब user कुछ बदलता है, तो settings event आता है।
livedeck.context
{ mode, format, locale, size, scale, test }। size CSS pixels में पेज का size है, scale resize किए गए widget का zoom (default पर 1)। mode live (OBS link), editor (preview) या demo (Marketplace) होता है।
livedeck.host
streamer का { handle, nickname, avatar }, सिर्फ़ host.profile permission के साथ, वरना null।
livedeck.image(ref)
तस्वीर reference (avatar, gift.image) को local तस्वीर पते में बदलता है। पते या null के साथ Promise।
livedeck.media.play(key, { volume })
media setting key का sound Livedeck के ज़रिए master volume के साथ चलाता है। volume 0 से 1। media.play ज़रूरी है। true या false के साथ Promise।
livedeck.media.url(key)
media setting key की तस्वीर या क्लिप का local पता। पते या null के साथ Promise।
livedeck.version
"1"
| Call | यह क्या करता है |
|---|---|
| livedeck.on(type, fn) | इस type के हर event पर fn को call करता है। एक function लौटाता है जो fn को फिर से हटा देता है। |
| livedeck.off(type, fn) | fn को हटाता है। |
| livedeck.ready(fn) | overlay connect होते ही और settings आते ही fn को call करता है। एक Promise भी लौटाता है। |
| livedeck.settings | मौजूदा settings (read-only)। जब user कुछ बदलता है, तो settings event आता है। |
| livedeck.context | { mode, format, locale, size, scale, test }। size CSS pixels में पेज का size है, scale resize किए गए widget का zoom (default पर 1)। mode live (OBS link), editor (preview) या demo (Marketplace) होता है। |
| livedeck.host | streamer का { handle, nickname, avatar }, सिर्फ़ host.profile permission के साथ, वरना null। |
| livedeck.image(ref) | तस्वीर reference (avatar, gift.image) को local तस्वीर पते में बदलता है। पते या null के साथ Promise। |
| livedeck.media.play(key, { volume }) | media setting key का sound Livedeck के ज़रिए master volume के साथ चलाता है। volume 0 से 1। media.play ज़रूरी है। true या false के साथ Promise। |
| livedeck.media.url(key) | media setting key की तस्वीर या क्लिप का local पता। पते या null के साथ Promise। |
| livedeck.version | "1" |
इवेंट्स
gift
Permission: events.gift
फ़ील्ड: user, gift { id, name, image, diamonds }, count, totalDiamonds, combo { count, ended }, toGuest
chat
Permission: events.chat
फ़ील्ड: user (साथ में isModerator, isSubscriber, fanLevel), text
like
Permission: events.like
फ़ील्ड: user (या null), count, total
follow
Permission: events.follow
फ़ील्ड: user
share
Permission: events.share
फ़ील्ड: user
join
Permission: events.join
फ़ील्ड: user
fanclub
Permission: events.fanclub
फ़ील्ड: user
viewers
Permission: events.viewers
फ़ील्ड: count
stream
Permission: stream.status
फ़ील्ड: status: live, offline या checking
settings
Permission: कोई नहीं
फ़ील्ड: नई settings
context
Permission: कोई नहीं
फ़ील्ड: नया context, जैसे नया size
ready
Permission: कोई नहीं
फ़ील्ड: connect होने के बाद एक बार
*
Permission: कोई नहीं
फ़ील्ड: ऊपर का हर live event
| टाइप | Permission | फ़ील्ड |
|---|---|---|
| gift | events.gift | user, gift { id, name, image, diamonds }, count, totalDiamonds, combo { count, ended }, toGuest |
| chat | events.chat | user (साथ में isModerator, isSubscriber, fanLevel), text |
| like | events.like | user (या null), count, total |
| follow | events.follow | user |
| share | events.share | user |
| join | events.join | user |
| fanclub | events.fanclub | user |
| viewers | events.viewers | count |
| stream | stream.status | status: live, offline या checking |
| settings | कोई नहीं | नई settings |
| context | कोई नहीं | नया context, जैसे नया size |
| ready | कोई नहीं | connect होने के बाद एक बार |
| * | कोई नहीं | ऊपर का हर live event |
हर live event में type और id होते हैं। user { handle, nickname, avatar } है: handle बिना @ के TikTok username है, avatar livedeck.image() के लिए तस्वीर reference। Viewers को उनके username ("@" + handle) से दिखाएँ। nickname वह display name है जो viewer ने खुद लिखा है और अक्सर असली नाम होता है: इसे न दिखाएँ। Widget को कभी भी TikTok number IDs, e-mail पते या links नहीं मिलते।
{
"type": "gift",
"id": "42",
"user": { "handle": "lena.loops", "nickname": "Lena", "avatar": "i:7" },
"gift": { "id": 5655, "name": "Rose", "image": "i:8", "diamonds": 1 },
"count": 3,
"totalDiamonds": 3,
"combo": { "count": 7, "ended": false },
"toGuest": false
}गिफ़्ट्स
- gift.diamonds एक gift की coin कीमत है। count इस event में नए gifts की संख्या है, totalDiamonds = count × gift.diamonds, यानी इससे जुड़ने वाले coins। Combos पहले से हिसाब में लिए जा चुके हैं: बस count और totalDiamonds जोड़ें, और कुछ नहीं।
- combo पूरी streak है, सिर्फ़ दिखाने के लिए ("Rose ×7"): combo.count अब तक के गिफ़्ट, और TikTok के बंद करते ही combo.ended. combo.count को कभी न जोड़ें और न ही उससे गुणा करें।
- कॉइन की वैल्यू हमेशा event से आती है। अपनी प्राइस लिस्ट कभी इस्तेमाल न करें और गिफ़्ट के नाम से कीमत का अंदाज़ा न लगाएँ।
- सबसे बड़ा single गिफ़्ट: gift.diamonds की तुलना करें। टॉप सपोर्टर / leaderboard: हर user.handle के लिए totalDiamonds जोड़ें।
- multi-guest LIVE में गिफ़्ट किसी गेस्ट को गया हो तो toGuest true होता है।
- किसी खास गिफ़्ट के लिए gift टाइप की setting इस्तेमाल करें और e.gift.id की तुलना उसकी वैल्यू से करें।
लाइक्स
LIVE के दौरान Livedeck हर 500 ms की लाइक्स को एक event में जोड़ता है: count उस समय का योग है, total पूरे LIVE की कुल संख्या।
उदाहरण: गिफ़्ट गोल
यह "manifest.json reference" पेज वाले manifest.json से मेल खाता है। पेज में #bar और #label एलिमेंट होना ज़रूरी है।
let total = 0;
let reached = false;
function render() {
const goal = Number(livedeck.settings.goal) || 100;
const bar = document.getElementById("bar");
bar.style.width = Math.min(total / goal, 1) * 100 + "%";
bar.style.background = livedeck.settings.accent;
document.getElementById("label").textContent = total + " / " + goal;
if (!reached && total >= goal) {
reached = true;
if (livedeck.settings.doneSound) livedeck.media.play("doneSound", { volume: 0.8 });
}
}
livedeck.on("gift", (e) => {
const only = livedeck.settings.giftId;
if (only && e.gift.id !== only) return;
total += e.count; // counts gifts; for a diamond goal use e.totalDiamonds
render();
});
livedeck.on("settings", render);
livedeck.ready(render);उदाहरण: प्रोफ़ाइल फ़ोटो के साथ चैट
livedeck.on("chat", async (e) => {
const row = document.createElement("div");
const img = document.createElement("img");
img.alt = "";
row.append(img, "@" + e.user.handle + ": " + e.text);
document.getElementById("chat").prepend(row);
// picture reference → local address (or null, then it stays empty)
const url = await livedeck.image(e.user.avatar);
if (url) img.src = url;
});जानने लायक बातें
- नाम और चैट टेक्स्ट दर्शक लिखते हैं। इन्हें हमेशा textContent से डालें, कभी innerHTML से नहीं।
- widget के पास कोई browser storage नहीं है: localStorage, sessionStorage, IndexedDB और cookies ब्लॉक हैं। अपनी state memory में रखें। यूज़र overlay रीलोड करे तो widget फिर से शुरू होता है।
- लोडिंग सिर्फ़ आपके अपने पैकेज से होती है। दूसरी साइट्स पर fetch, WebSockets, frames, forms, pop-ups और पेज से बाहर जाना ब्लॉक है।
- overlay हर 2000 ms पर चेक करता है कि आपका widget अभी भी जवाब दे रहा है या नहीं। जब तक आपका कोड browser को ब्लॉक नहीं करता, SDK खुद जवाब देता है।
- LIVE के दौरान एक widget को प्रति सेकंड ज़्यादा से ज़्यादा 50 मैसेज मिलते हैं। बहुत ज़्यादा events होने पर गिफ़्ट और चैट को प्राथमिकता मिलती है।
- आपका widget overlay को प्रति सेकंड ज़्यादा से ज़्यादा 10 requests भेज सकता है (जैसे livedeck.image), हर एक अधिकतम 64 KB की। SDK तस्वीरें याद रखता है, इसलिए एक ही reference सिर्फ़ एक बार गिना जाता है।
- livedeck.media.play से चलाई गई आवाज़ें Livedeck के audio से होकर जाती हैं, इसलिए master volume और यूज़र का चुना output लागू होता है। आप अपने पैकेज की आवाज़ें <audio> से भी चला सकते हैं, लेकिन वे Livedeck के volume को बायपास करती हैं।
- fonts को .woff2 के रूप में पैकेज में डालें और @font-face व relative path से लोड करें। आप तस्वीरें खुद भी बना सकते हैं (canvas, data:, blob:)।
क्या यह लेख मददगार था?