لصنّاع المحتوى والمصممين

Widget SDK

اصنع طبقات بث خاصة بك بلغات HTML وCSS وJavaScript. يصل إلى الويدجت كل هدية وإعجاب ومتابعة ورسالة دردشة في بثك على TikTok وTwitch وYouTube وKick، بالعربية والإنجليزية، ويظهر في البث مثل أي طبقة من طبقات CheerQuake.

15قالبًا جاهزًا

13نوعًا من الإعدادات

0خوادم لتشغيلها

ابدأ خلال دقيقة

1
افتح ويدجتاتي
في CheerQuake: طبقات البث ← ويدجتاتي ← ويدجت جديد.
2
اختر قالبًا
صاروخ الهدايا أو فقاعات الدردشة أو أكبر الداعمين أو الهدف أو العدّ التنازلي أو تصويت الدردشة أو عدّاد الحماس… أو ويدجت فارغ، أو واحدًا من معرض المجتمع.
3
عدّله
إعداداته في صفحته، أو أي شيء تريده عبر تعديل الكود. والمعاينة تعرض تغييراتك فورًا.
4
ضعه في البث
انسخ رابطه في TikTok LIVE Studio (إضافة مصدر ← رابط) أو OBS (المصادر ← + ← متصفح)، أو أضفه إلى مشهد.

مما يتكوّن الويدجت

الويدجت صفحة ويب صغيرة. وفي المحرّر خمسة تبويبات:

HTML	ما يعرضه الويدجت. ‏`{{id}}` يضع هنا قيمة أحد الإعدادات.
CSS	شكله. و`{{id}}` تعمل هنا أيضًا، مثل `color: {{accent}};`.
JavaScript	ما يفعله. ‏`CQ` هي الـ SDK، جاهزة قبل أن يعمل الكود.
حقول الإعدادات	الإعدادات التي يجدها صانع المحتوى في صفحة الويدجت (قائمة بصيغة JSON).
تفاصيل	اسمه ومؤلفه ووصفه وحجمه.

الأحداث

استدعِ CQ.on(type, fn) لتستمع إلى حدث. وهي تُرجع دالة توقف الاستماع.

CQ.on('gift', (ev) => {
  console.log(ev.user.name, ev.amount, ev.gift.name, ev.coins);
});

`'gift'`	هدية. السلسلة ترسل عدة أحداث: ‏`amount` ما يضيفه هذا الحدث، و`total` مجموع السلسلة حتى الآن.
`'follow'`	متابع جديد.
`'like'`	إعجابات: ‏`amount` إعجاب.
`'share'`	شارك أحدهم البث.
`'chat'`	رسالة دردشة: ‏`text`.
`'subscribe'`	اشتراك (TikTok وTwitch وYouTube وKick).
`'event'`	كل ما سبق.
`'alert'`	تنبيه يعرضه CheerQuake (عنوانه ورسالته وصورته…).
`'goal'`	تحقّق هدف: ‏`{ id, target }`.
`'button'`	ضُغط إعداد من نوع زر: معرّفه.
`'settings'`	غيّر صانع المحتوى الإعدادات. ومن دونه يبدأ الويدجت من جديد بها.
`'state'`	أرقام بث جديدة (`CQ.state`).
`'message'`	كل رسالة يرسلها CheerQuake إلى طبقات البث (المؤقت والعجلة والتصويت والمعركة…).
`'ready'`	الصفحة جاهزة.

الحدث

لكل أحداث المشاهدين الشكل نفسه:

`ev.type`	‏`gift` أو `follow` أو `like` أو `share` أو `chat` أو `subscribe`
`ev.user`	‏`{ name, username, avatar, rank }`
`ev.gift`	‏`{ name, image, emoji, coins }` (للهدايا فقط؛ وقد يكون `image` فارغًا: اعرض الرمز التعبيري)
`ev.amount`	الهدايا أو الإعجابات في هذا الحدث (1 للباقي)
`ev.total`	الهدايا حتى الآن في هذه السلسلة
`ev.coins`	العملات التي يضيفها هذا الحدث (العدد × عملات الهدية)
`ev.text`	رسالة الدردشة
`ev.platform`	‏`tiktok` أو `twitch` أو `youtube` أو `kick` أو `bot`
`ev.test`	‏`true` للأحداث التجريبية
`ev.streak`	نفسه لكل أحداث سلسلة الهدية الواحدة

CQ: كل ما يستطيع الكود استخدامه

`CQ.on(type, fn) · CQ.off(type, fn)`	الاستماع إلى حدث أو إيقافه.
`CQ.settings`	الإعدادات حسب المعرّف: ‏`CQ.settings.title`.
`CQ.state`	أرقام البث (في الأسفل).
`CQ.lang · CQ.dir`	‏`en` أو `ar`؛ و`ltr` أو `rtl`.
`CQ.T(english, arabic)`	النص بلغة CheerQuake. وتعمل `CQ.T({ en, ar })` أيضًا.
`CQ.store.get(key, otherwise) · set(key, value) · remove(key) · clear()`	أشياء صغيرة تُحفظ بين مرات إعادة التحميل (100 كيلوبايت على الأكثر)، يحفظها مصدر المتصفح الذي يعرض الويدجت.
`CQ.queue(async () => …)`	مهام واحدة بعد الأخرى، مثل تنبيهات تنتظر دورها.
`CQ.wait(ms)`	انتظار: ‏`await CQ.wait(1500)`.
`CQ.play(url, volume)`	تشغيل صوت، مثل إعداد من نوع صوت.
`CQ.giftPicture(gift, size) · CQ.avatar(user, size)`	صورة هدية أو صورة مشاهد، جاهزة للإضافة إلى الصفحة.
`CQ.el(tag, class, text)`	عنصر جديد.
`CQ.fmt(n)`	رقم بالأرقام الغربية: 1,234.
`CQ.esc(text)`	نص آمن لـ innerHTML.
`CQ.bidi(text)`	اسم أو رسالة يحافظ على اتجاهه داخل نص آخر.
`CQ.isRtl(text)`	هل يبدأ النص بحرف يُكتب من اليمين؟
`CQ.font(name)`	تحميل خط من Google Fonts وإعطاء اسمه لـ font-family.
`CQ.test(type)`	حدث تجريبي لهذا الويدجت فقط.
`CQ.log(…)`	سطر في وحدة التحكم في المحرّر.
`CQ.demo`	‏`true` في المعاينات، حيث تأتي الأحداث التجريبية وحدها.
`CQ.widget`	‏`{ id, name, width, height }`.

CQ.state: أرقام البث

تصل CQ.state بعد البدء بلحظة وتتغيّر أثناء البث:

`CQ.state.live`	هل البث مباشر الآن؟
`CQ.state.session`	‏`{ viewers, likes, coins, gifts, follows, shares, subs, chats, startedAt }`
`CQ.state.top`	أكبر الداعمين: ‏`[{ name, avatar, coins, … }]`
`CQ.state.boards`	‏`{ coins, likes, shares, chats }`: لوحات المتصدرين
`CQ.state.goals`	‏`[{ id, name, current, target }]`
`CQ.state.recent`	آخر الأحداث، بشكل الحدث نفسه
`CQ.state.last`	آخر متابع وآخر داعم وآخر مشارك…
`timer · wins · points`	مؤقت الساباثون وهدف الانتصارات ونقاط CQ

الإعدادات

حقول الإعدادات قائمة. لكل حقل id (اسمه في CQ.settings) وtype وlabel وdefault. ويمكن أن يكون العنوان والقيمة النصية الافتراضية باللغتين.

`text · textarea`	نص
`number`	رقم (`min` و`max` و`step`)
`slider`	شريط تمرير (`min` و`max` و`step`)
`color`	لون: ‏`#ff8a1f`
`toggle`	تشغيل أو إيقاف
`select`	اختيار: ‏`options: [["top", "Top"], ["bottom", "Bottom"]]`
`image · video`	صورة أو فيديو: صور CheerQuake أو صور صانع المحتوى
`sound`	صوت من مكتبة CheerQuake أو من أصوات صانع المحتوى
`font`	خط من Google Fonts (Cairo وTajawal وChanga وLalezar…) يُحمَّل تلقائيًا
`button`	زر في صفحة الويدجت: يسمعه الكود بـ `CQ.on('button')`
`heading`	عنوان بين الإعدادات

Settings fields

[
  { "id": "title", "type": "text", "label": { "en": "Title", "ar": "العنوان" },
    "default": { "en": "Gifts:", "ar": "الهدايا:" } },
  { "id": "color", "type": "color", "label": "Color", "default": "#ff8a1f" },
  { "id": "font", "type": "font", "label": "Font", "default": "Cairo" },
  { "id": "reset", "type": "button", "label": { "en": "Reset", "ar": "إعادة الضبط" } }
]

ويدجت كامل

عدّاد هدايا يتذكّر عدده، في نحو 20 سطرًا:

HTML

<div class="box">{{title}} <b id="n">0</b></div>

CSS

.box {
  padding: 14px 18px;
  border-radius: 16px;
  background: rgba(10, 16, 36, 0.9);
  color: #fff;
  font: 800 28px "{{font}}", sans-serif;
}
.box b { color: {{color}}; }

JavaScript

const n = document.getElementById('n');
let gifts = CQ.store.get('gifts', 0);
n.textContent = CQ.fmt(gifts);

CQ.on('gift', (ev) => {
  gifts += ev.amount;
  CQ.store.set('gifts', gifts);
  n.textContent = CQ.fmt(gifts);
});

// A "Reset" button in the settings.
CQ.on('button', (id) => {
  if (id !== 'reset') return;
  gifts = 0;
  CQ.store.set('gifts', 0);
  n.textContent = '0';
});

العربية والكتابة من اليمين

صُنع CheerQuake للعربية والإنجليزية. وبعض العادات تجعل الويدجت يبدو صحيحًا باللغتين:

اكتب كل نص بـ CQ.T('Thank you', 'شكرًا')، أو كإعداد قيمته الافتراضية باللغتين.
صفحة الويدجت مضبوطة على lang وdir مسبقًا: استخدم margin-inline-start وtext-align: start وflexbox، لا left وright.
أعطِ الأسماء والرسائل dir="auto" (أو CQ.bidi() داخل جملة): فيبقى الاسم الإنجليزي في مكانه داخل نص عربي.
‏CQ.fmt() يحافظ على الأرقام الغربية (1,234) باللغتين.
خطوط عربية: Cairo وTajawal وAlmarai وChanga وEl Messiri وLalezar وReem Kufi وAmiri وBaloo Bhaijaan 2.

title.textContent = CQ.T('Thank you!', 'شكرًا لك!');
name.dir = 'auto';
line.innerHTML = `${CQ.esc(CQ.bidi(ev.user.name))} ${CQ.T('sent', 'أرسل')} ${CQ.fmt(ev.amount)}`;

مشاركة ويدجت

في صفحة الويدجت يحفظه تصدير… في ملف .cqwidget واحد: الكود وحقول الإعدادات والإعدادات. ويضيف استيراد… في ويدجتاتي ملفًا شاركه معك شخص آخر. والملف بصيغة JSON:

.cqwidget

{
  "format": "cheerquake-widget",
  "formatVersion": 1,
  "name": "Gift counter",
  "author": "Your name",
  "description": "…",
  "version": "1.0",
  "size": { "w": 600, "h": 300 },
  "html": "…", "css": "…", "js": "…",
  "fields": [ … ],
  "values": { "title": "Gifts:" }
}

معرض المجتمع

معرض المجتمع في ويدجتاتي هو المكان الذي يشارك فيه صنّاع المحتوى ويدجتاتهم مع الجميع. ابحث فيه، وصفِّه حسب الفئة، ورتّبه حسب الأحدث أو الأكثر إضافة أو الأكثر إعجابًا، وشاهد كل ويدجت يعمل في معاينته.
يضع إضافة نسخة في ويدجتاتي: غيّر إعداداتها أو الكود كما تشاء، فهي لك.
لتشارك ويدجتك افتحه وانقر مشاركة في المعرض: اسمه، واسمك كمؤلف له (لا بريدك الإلكتروني أبدًا)، وفئة ووصف. وغيّره لاحقًا ثم تحديث في المعرض؛ وإزالة من المعرض تُخرجه (ويحتفظ من أضافه بنسخته).
أعجب بالويدجتات التي تحبها. وبلّغ عن ويدجت مسيء أو للبالغين أو منسوخ أو لا يعمل: الويدجت الذي يبلّغ عنه عدة صنّاع محتوى يُخفى حتى نراجعه. وعلى الأكثر 20 مشاركة في اليوم و100 ويدجت لكل صانع محتوى.

التجربة

تصل الأحداث التجريبية إلى معاينة المحرّر وحدها (أوقف أحداث تجريبية لإيقافها)، وترسل أزرار إرسال تجربة حدثًا من كل نوع. وتظهر الأخطاء وأسطر console.log في وحدة التحكم مع رقم سطر JavaScript: انقره لتنتقل إليه. وأحداث بثك الحقيقي تصل إلى المعاينة أيضًا.

الأمان والحدود

يعمل الويدجت داخل بيئة معزولة: لا يصل إلى الصفحة من حوله ولا إلى CheerQuake ولا إلى الويدجتات الأخرى ولا إلى جهاز صانع المحتوى.
لا يستطيع تحميل سكربتات من مواقع أخرى ولا الاتصال بأي مكان (fetch وWebSocket) ولا تشغيل كود من نص (eval). ضع كل الكود في تبويب JavaScript.
الصور والأصوات والفيديو وخطوط Google تُحمَّل من أي مكان.
على الأكثر 300 كيلوبايت لكلٍّ من HTML وCSS وJavaScript، و80 إعدادًا، و100 كيلوبايت في CQ.store.
في البث لا تظهر أخطاء الويدجت أبدًا: تظهر في المعاينات وفي وحدة التحكم في المحرّر.