Livedeck widget SDK: פונקציות ואירועים
כל מה שהאובייקט livedeck עושה: אירועים, הגדרות, תמונות, צלילים והקשר.
ה־SDK הוא ספרייה קטנה ש־Livedeck מגישה בכתובת של כל ווידג’ט תחת /sdk/v1.js. היא מחברת את הווידג’ט שלך לאוברליי ומספקת את האובייקט livedeck.
<script src="/sdk/v1.js"></script>טענו אותה לפני הקוד שלכם. ברגע שהעמוד נטען, ה־SDK מתחבר לאוברליי בעצמו. לא צריך לקרוא לשום דבר בשביל זה.
פונקציות
livedeck.on(type, fn)
קורא ל־fn בכל אירוע מהסוג הזה. מחזיר פונקציה שמסירה את fn שוב.
livedeck.off(type, fn)
מסיר את fn.
livedeck.ready(fn)
קורא ל־fn ברגע שהאוברליי מחובר וההגדרות הגיעו. מחזיר גם Promise.
livedeck.settings
ההגדרות הנוכחיות (לקריאה בלבד). כשהמשתמש משנה משהו, מגיע האירוע settings.
livedeck.context
{ mode, format, locale, size, scale, test }. size הוא גודל העמוד בפיקסלי CSS, scale הוא הזום של הווידג’ט אחרי שינוי גודל (1 כברירת מחדל). mode הוא live (קישור OBS), editor (תצוגה מקדימה) או demo (Marketplace).
livedeck.host
{ handle, nickname, avatar } של הסטרימר, רק עם ההרשאה host.profile, אחרת null.
livedeck.image(ref)
הופך הפניה לתמונה (avatar, gift.image) לכתובת תמונה מקומית. Promise עם הכתובת או null.
livedeck.media.play(key, { volume })
משמיע את הצליל מהגדרת המדיה key דרך Livedeck, עם עוצמת הקול הראשית. volume בין 0 ל־1. דורש media.play. Promise עם true או false.
livedeck.media.url(key)
כתובת מקומית של התמונה או הקליפ מהגדרת המדיה key. Promise עם הכתובת או null.
livedeck.version
"1"
| קריאה | מה זה עושה |
|---|---|
| livedeck.on(type, fn) | קורא ל־fn בכל אירוע מהסוג הזה. מחזיר פונקציה שמסירה את fn שוב. |
| livedeck.off(type, fn) | מסיר את fn. |
| livedeck.ready(fn) | קורא ל־fn ברגע שהאוברליי מחובר וההגדרות הגיעו. מחזיר גם Promise. |
| livedeck.settings | ההגדרות הנוכחיות (לקריאה בלבד). כשהמשתמש משנה משהו, מגיע האירוע settings. |
| livedeck.context | { mode, format, locale, size, scale, test }. size הוא גודל העמוד בפיקסלי CSS, scale הוא הזום של הווידג’ט אחרי שינוי גודל (1 כברירת מחדל). mode הוא live (קישור OBS), editor (תצוגה מקדימה) או demo (Marketplace). |
| livedeck.host | { handle, nickname, avatar } של הסטרימר, רק עם ההרשאה host.profile, אחרת null. |
| livedeck.image(ref) | הופך הפניה לתמונה (avatar, gift.image) לכתובת תמונה מקומית. Promise עם הכתובת או null. |
| livedeck.media.play(key, { volume }) | משמיע את הצליל מהגדרת המדיה key דרך Livedeck, עם עוצמת הקול הראשית. volume בין 0 ל־1. דורש media.play. Promise עם true או false. |
| livedeck.media.url(key) | כתובת מקומית של התמונה או הקליפ מהגדרת המדיה key. Promise עם הכתובת או null. |
| livedeck.version | "1" |
אירועים
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
הרשאה: אין
שדות: ההגדרות החדשות
context
הרשאה: אין
שדות: ההקשר החדש, למשל גודל חדש
ready
הרשאה: אין
שדות: פעם אחת אחרי ההתחברות
*
הרשאה: אין
שדות: כל אירוע לייב שלמעלה
| סוג | הרשאה | שדות |
|---|---|---|
| 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 | אין | ההגדרות החדשות |
| context | אין | ההקשר החדש, למשל גודל חדש |
| ready | אין | פעם אחת אחרי ההתחברות |
| * | אין | כל אירוע לייב שלמעלה |
לכל אירוע לייב יש type ו־id. user הוא { handle, nickname, avatar }: handle הוא שם המשתמש ב־TikTok בלי @, avatar הוא הפניה לתמונה עבור livedeck.image(). הציגו צופים לפי שם המשתמש שלהם ("@" + handle). nickname הוא שם התצוגה שהצופה הקליד ולעיתים קרובות זה שם אמיתי: אל תציגו אותו. ווידג’ט אף פעם לא מקבל מזהים מספריים של TikTok, כתובות אימייל או קישורים.
{
"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 הוא מחיר המטבעות של מתנה אחת. count הוא מספר המתנות החדשות באירוע הזה, ו־totalDiamonds = count × gift.diamonds הם המטבעות שהוא מוסיף. קומבו כבר מקוזז: חברו את count ו־totalDiamonds, ולא יותר.
- combo הוא כל הרצף, לתצוגה בלבד ("Rose ×7"): combo.count הוא מספר המתנות עד עכשיו, ו-combo.ended מופיע כש-TikTok סוגרת אותו. אף פעם אל תחברו את combo.count ואל תכפילו בו.
- ערכי המטבעות תמיד מגיעים מהאירוע. אל תשתמשו ברשימת מחירים משלכם ואל תנחשו מחיר לפי שם המתנה.
- המתנה הבודדת הגדולה ביותר: השוו את gift.diamonds. תומך מוביל / טבלת מובילים: חברו את totalDiamonds לפי user.handle.
- toGuest הוא true כשהמתנה נשלחה לאורח ב-LIVE עם כמה אורחים.
- למתנה מסוימת, השתמשו בהגדרה מסוג gift והשוו את e.gift.id לערך שלה.
לייקים
במהלך ה-LIVE, Livedeck מאגדת לייקים כל 500 ms לאירוע אחד: count הוא הסכום בפרק הזמן הזה, ו-total הוא הספירה הכוללת של ה-LIVE.
דוגמה: יעד מתנות
תואם ל-manifest.json שבעמוד "manifest.json reference". העמוד צריך אלמנט #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.
- לווידג׳ט אין אחסון בדפדפן: localStorage, sessionStorage, IndexedDB ועוגיות חסומים. שמרו את המצב בזיכרון. כשהמשתמש טוען מחדש את האוברליי, הווידג׳ט מתחיל מההתחלה.
- טעינה אפשרית רק מהחבילה שלכם. fetch לאתרים אחרים, WebSockets, מסגרות, טפסים, חלונות קופצים וניווט החוצה חסומים.
- האוברליי בודק כל 2000 ms אם הווידג׳ט עדיין מגיב. ה-SDK עונה בעצמו כל עוד הקוד שלכם לא חוסם את הדפדפן.
- במהלך ה-LIVE ווידג׳ט מקבל לכל היותר 50 הודעות בשנייה. כשיש המון אירועים, מתנות וצ׳אט מקבלים עדיפות.
- הווידג׳ט יכול לשלוח לאוברליי לכל היותר 10 בקשות בשנייה (למשל livedeck.image), כל אחת עד 64 KB. ה-SDK זוכר תמונות, כך שאותה הפניה נספרת רק פעם אחת.
- צלילים שמושמעים עם livedeck.media.play עוברים דרך האודיו של Livedeck, כך שעוצמת הקול הראשית והפלט שהמשתמש בחר חלים עליהם. אפשר גם להשמיע צלילים מהחבילה עם <audio>, אבל הם עוקפים את עוצמת הקול של Livedeck.
- שימו גופנים בחבילה כקובצי .woff2 וטענו אותם עם @font-face ונתיב יחסי. מותר גם ליצור תמונות בעצמכם (canvas, data:, blob:).
המאמר הזה עזר לך?