Livedeck widget SDK: الدوال والأحداث

كل ما يفعله كائن livedeck: الأحداث والإعدادات والصور والأصوات والسياق.

قراءة في 9 دقيقة آخر تحديث 4 نوفمبر 2026

الـSDK مكتبة صغيرة يوفّرها Livedeck على عنوان كل widget تحت /sdk/v1.js. تربط الـwidget الخاص بك بالـoverlay وتوفّر كائن livedeck.

html
<script src="/sdk/v1.js"></script>

حمّلها قبل الكود الخاص بك. بمجرد تحميل الصفحة، يتصل الـSDK بالـoverlay تلقائيًا. لا تحتاج إلى استدعاء أي شيء لذلك.

الدوال

livedeck.on(type, fn)

يستدعي fn عند كل حدث من هذا النوع. يُرجع دالة تزيل fn مجددًا.

livedeck.off(type, fn)

يزيل fn.

livedeck.ready(fn)

يستدعي fn بمجرد اتصال الـoverlay ووصول الإعدادات. يُرجع أيضًا Promise.

livedeck.settings

الإعدادات الحالية (للقراءة فقط). عندما يغيّر المستخدم شيئًا، يصل حدث settings.

livedeck.context

{ mode, format, locale, size, scale, test }. ‏size هو حجم الصفحة بوحدات CSS pixel، وscale هو تكبير الـwidget بعد تغيير حجمه (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 هو الاسم المعروض الذي كتبه المشاهد وغالبًا ما يكون اسمًا حقيقيًا: لا تعرضه. لا يحصل الـwidget أبدًا على معرّفات 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". تحتاج الصفحة إلى عنصر #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 أبدًا.
  • لا يملك الـ widget أي تخزين في المتصفح: localStorage وsessionStorage وIndexedDB وملفات تعريف الارتباط محظورة. احتفظ بالحالة في الذاكرة. عندما يعيد المستخدم تحميل الـ overlay، يبدأ الـ widget من جديد.
  • التحميل ممكن فقط من حزمتك. طلبات fetch إلى مواقع أخرى وWebSockets والإطارات والنماذج والنوافذ المنبثقة والانتقال إلى صفحات أخرى كلها محظورة.
  • يتحقق الـ overlay كل 2000 ms مما إذا كان الـ widget لا يزال يستجيب. تردّ SDK تلقائيًا ما دام كودك لا يُجمّد المتصفح.
  • أثناء LIVE يتلقى الـ widget بحد أقصى 50 رسالة في الثانية. عند كثرة الأحداث، تكون الأولوية للهدايا والدردشة.
  • يمكن للـ widget إرسال 10 طلبات كحد أقصى في الثانية إلى الـ overlay (مثل livedeck.image)، وكل طلب بحد أقصى 64 KB. تتذكر SDK الصور، لذا يُحتسب المرجع نفسه مرة واحدة فقط.
  • الأصوات التي تُشغَّل عبر livedeck.media.play تمر عبر صوت Livedeck، فيُطبَّق مستوى الصوت الرئيسي والمخرج الذي اختاره المستخدم. يمكنك أيضًا تشغيل أصوات من حزمتك باستخدام <audio>، لكنها تتجاوز مستوى صوت Livedeck.
  • ضع الخطوط في الحزمة بصيغة .woff2 وحمّلها باستخدام @font-face ومسار نسبي. يمكنك أيضًا إنشاء الصور بنفسك (canvas وdata: وblob:).

هل كانت هذه المقالة مفيدة؟