Livedeck widget SDK: פונקציות ואירועים

כל מה שהאובייקט livedeck עושה: אירועים, הגדרות, תמונות, צלילים והקשר.

9 דק׳ קריאה עודכן ב-4 בנוב׳ 2026

ה־SDK הוא ספרייה קטנה ש־Livedeck מגישה בכתובת של כל ווידג’ט תחת ‎/sdk/v1.js. היא מחברת את הווידג’ט שלך לאוברליי ומספקת את האובייקט livedeck.

html
<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"

אירועים

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, כתובות אימייל או קישורים.

json
{
  "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.

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

דוגמה: צ׳אט עם תמונות פרופיל

js
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:).

המאמר הזה עזר לך?