Livedeck widget SDK: الدوال والأحداث
كل ما يفعله كائن livedeck: الأحداث والإعدادات والصور والأصوات والسياق.
الـSDK مكتبة صغيرة يوفّرها Livedeck على عنوان كل widget تحت /sdk/v1.js. تربط الـwidget الخاص بك بالـoverlay وتوفّر كائن livedeck.
<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"
| الاستدعاء | الوظيفة |
|---|---|
| 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
الصلاحية: لا شيء
الحقول: مرة واحدة بعد الاتصال
*
الصلاحية: لا شيء
الحقول: كل أحداث البث المباشر أعلاه
| النوع | الصلاحية | الحقول |
|---|---|---|
| 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 الرقمية أو عناوين البريد الإلكتروني أو الروابط.
{
"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.
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 أي تخزين في المتصفح: 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:).
هل كانت هذه المقالة مفيدة؟