أرسل رسائل مباشرة وحضورًا باستخدام JavaScript SDK
التدفقات اليومية لـ aura.realtime، مع سلوك كل مكالمة كما لوحظ مقابل مكدس قيد التشغيل.
القنوات وحالتها#
القناة عبارة عن غرفة مسماة. العملاء الذين يفتحون نفس الاسم يتلقون رسائل بعضهم البعض. يتصل العميل من تلقاء نفسه عند الاشتراك.
const room = aura.realtime.channel('room-1')
room.subscribe((status) => {
// "مشترك" | "خطأ في القناة" | "TIMED_OUT" | "مغلق"
if (status === 'SUBSCRIBED') console.log('ready')
})
أرسل فقط بعد SUBSCRIBED. قبل ذلك، أو بعد الرفض، يُرجع send() حالة مثل not_connected أو requires_subscription بدلاً من الإرسال. يتم تحديد نطاق القنوات وفقًا لمشروعك: يمكن لمشروعين استخدام نفس الاسم دون رؤية بعضهما البعض.
رسائل البث#
// تلقي
room.on('broadcast', { event: 'ping' }, (message) => {
console.log(message.payload) // { الحدث: 'ping'، n: 1، النص: 'hello' }
})
// أرسل بمجرد الاشتراك
const status = await room.send({ type: 'broadcast', event: 'ping', payload: { n: 1, text: 'hello' } })
// → "حسنا"
وفي التشغيل الحقيقي، تلقى العميل الثاني الذي قام بتسجيل الدخول الرسالة في أقل من ثانيتين.
تحتوي الرسالة التي تتلقاها على اسم الحدث المضاف إلى payload: { "event": "ping", "n": 1, … }. تم رفض الحمولة التي تحتوي على مفتاح event الخاص بها (channel.send ترجع 'invalid_payload'، httpBroadcast ترجع realtime_payload_event_reserved): أعد تسمية المفتاح، على سبيل المثال kind.
- لا تتلقى رسائلك الخاصة بشكل افتراضي. افتح القناة بـ
{ config: { broadcast: { self: true } } }لاستقبالهم. - تحمل الرسالة
idوtopicوtimestampوeventوpayload.
وجود#
يظهر الحضور الأشخاص المتصلين بالقناة، مع الحالة التي تختارها.
const lobby = aura.realtime.channel('lobby', { config: { presence: { key: user.id } } })
lobby.on('presence', { event: 'sync' }, () => {
console.log(lobby.presenceState())
})
lobby.subscribe(async (status) => {
if (status === 'SUBSCRIBED') await lobby.track({ name: 'Bob' })
})
يتم ربط presenceState() بواسطة معرف المستخدم. يسرد كل إدخال اتصالات المستخدم:
{
"d6ba3994-…": [
{ "client_id": "936cb015-…", "user_id": "d6ba3994-…", "metadata": { "name": "Bob" },
"joined_at": "2026-10-12T19:32:19.093Z", "last_seen": "2026-10-12T19:32:19.096Z" }
]
}
untrack() يزيلك من القائمة، وترك القناة أو إغلاق الصفحة يفعل ذلك نيابة عنك.
تغييرات قاعدة البيانات#
postgres_changes يعمل على المشاريع باستخدام قاعدة البيانات الخاصة به. قم بتمكين كل جدول أولاً: PUT /v1/db/schema/tables/{table}/realtime (أو aura db table realtime <table> on) مع النص {"enabled": true} ومفتاح service_role. يبدأ الاستماع عندما يشترك العميل الأول ويتوقف بعد دقائق قليلة من مغادرة العميل الأخير. يتم التسليم مرة واحدة على الأقل: بعد إعادة تشغيل الخادم، يمكن أن يصل التغيير مرتين، لذا اجعل المعالج الخاص بك غير فعال، على سبيل المثال عن طريق الضغط على المفتاح الأساسي للصف. يمكن أن ترفض المجموعة المزدحمة مستمعًا جديدًا بسبب وجود خطأ في السعة؛ أعد المحاولة بعد قليل. يعمل أي اسم قناة: يقوم كل مرشح table بتحديد الجدول للاستماع إليه، ويمكن لقناة واحدة الاستماع إلى عدة جداول. في قناة غير مسماة db:<schema>.<table>، يحتاج كل مرشح إلى table. يمكن للمشترك الأول الحصول على ما يصل إلى 5 ثوانٍ من التغييرات التي تم إجراؤها قبل الاشتراك مباشرةً. يتم الاحتفاظ بالتغييرات لمدة ساعة واحدة لاستردادها، ثم يتم حذفها. عندما تكون المجموعة ممتلئة، يفشل الاشتراك مع capacité d'écoute postgres_changes atteinte pour la base de ce projet, réessayez. إذا ظل الاستماع معطلاً لأكثر من دقيقة، تنتقل القناة إلى CHANNEL_ERROR، ثم تعود إلى SUBSCRIBED بمجرد استعادة الاستماع؛ لا تحتاج للاشتراك مرة أخرى. إذا استمر الانقطاع لمدة ساعة واحدة، فستستقبل القناة أيضًا CHANNEL_ERROR مع changements postgres_changes perdus pendant l'interruption, resynchronisez: إعادة تحميل البيانات من قاعدة البيانات. يحتفظ التغيير بنفس id في كل مرة يتم تسليمه، لذا يمكنك أيضًا تخطي id الذي قمت بمعالجته بالفعل. لم يعد صف الحذف موجودًا، لذلك لا يمكن تقييم الأمان على مستوى الصف عليه. في جدول يتمتع بأمان على مستوى الصف، يتم تسليم DELETE فقط للمشتركين الذين يمتلك دورهم سياسة SELECT على الطاولة (أو يتجاوز RLS، مثل service_role): الزائر (anon) بدون سياسة القراءة لا يستقبله. على جدول بدون أمان على مستوى الصف، يحصل عليه كل مشترك. payload.old من DELETE يحتوي فقط على أعمدة المفاتيح الأساسية (لا شيء إذا لم يكن الجدول يحتوي على مفتاح أساسي)، ولا يطابق المرشح الموجود على أي عمود آخر عملية الحذف أبدًا. بالنسبة إلى UPDATE، يحتفظ payload.old أيضًا بأعمدة المفاتيح الأساسية للصف السابق فقط (قيمها السابقة إذا تغير المفتاح)، وليس القيم الأخرى أبدًا: يتم التحقق من أمان مستوى الصف في الصف الجديد فقط. ينطبق مرشح UPDATE على الصف الجديد. احتفظ بالمعلومات الحساسة بعيدًا عن المفاتيح الأساسية.
const changes = aura.realtime
.channel('todos')
.on('postgres_changes', { event: '*', schema: 'public', table: 'todos' }, (payload) => {
console.log(payload.eventType, payload.new)
})
.subscribe((status) => {
if (status === 'CHANNEL_ERROR') console.warn('database changes are not available for this project')
})
تنظيف#
room.unsubscribe() // ترك قناة واحدة
aura.realtime.removeChannel(room) // ترك وننسى ذلك
aura.realtime.removeAllChannels() // اترك كل قناة
aura.realtime.disconnect() // أغلق الاتصال
شاهد الاتصال مع aura.realtime.onStateChange(callback) و onError(callback). بعد انقطاع الاتصال، يقوم العميل بإعادة الاتصال بنفسه ما لم تتصل بـ setAutoReconnect(false).