شعار أوراباسي
aurabaseمستندات
مستندات›أدلة›Realtime and presence (SDK)

أرسل رسائل مباشرة وحضورًا باستخدام JavaScript SDK

التدفقات اليومية لـ aura.realtime، مع سلوك كل مكالمة كما لوحظ مقابل مكدس قيد التشغيل.

7 د قراءة·المستوى وسيطة·تمت المراجعة في 12‏/10‏/2026
تم إنشاء هذا النص الإنجليزي تلقائيًا من النص الأصلي الفرنسي ولم تتم مراجعته بعد.
لقد تغير المصدر الإنجليزي منذ هذه الترجمة. قد تكون بعض المعلومات قديمة.
تمت ترجمة هذه الصفحة تلقائيًا. النسخة الإنجليزية موثوقة.
#
القنوات

1. القنوات وحالتها

القناة عبارة عن غرفة مسماة. العملاء الذين يفتحون نفس الاسم يتلقون رسائل بعضهم البعض. يتصل العميل من تلقاء نفسه عند الاشتراك.

channel.tstypescript
const room = aura.realtime.channel('room-1')

room.subscribe((status) => {
  // "مشترك" | "خطأ في القناة" | "TIMED_OUT" | "مغلق"
  if (status === 'SUBSCRIBED') console.log('ready')
})

أرسل فقط بعد SUBSCRIBED. قبل ذلك، أو بعد الرفض، تقوم send() بإرجاع حالة مثل not_connected أو requires_subscription بدلاً من الإرسال. يتم تحديد نطاق القنوات وفقًا لمشروعك: يمكن لمشروعين استخدام نفس الاسم دون رؤية بعضهما البعض.

#
بث

2. بث الرسائل

broadcast.tstypescript
// تلقي
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' } })
// → "حسنا"

وفي التشغيل الحقيقي، تلقى العميل الثاني الذي قام بتسجيل الدخول الرسالة في أقل من ثانيتين.

تحمل الحمولة مفتاح event

تتضمن الرسالة التي تتلقاها اسم الحدث المضاف إلى payload: { "event": "ping", "n": 1, … }. يُرفض أي payload يحمل مفتاح event خاصًا به (تُرجع channel.send القيمة 'invalid_payload'، وتُرجع httpBroadcast الخطأ realtime_payload_event_reserved): أعد تسمية المفتاح، مثلًا kind.

  • لا تتلقى رسائلك الخاصة بشكل افتراضي. افتح القناة بـ { config: { broadcast: { self: true } } } لاستقبالهم.
  • تحمل الرسالة id و topic و timestamp و event و payload.
#
وجود

3. الحضور

يظهر الحضور الأشخاص المتصلين بالقناة، مع الحالة التي تختارها.

presence.tstypescript
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() بواسطة معرف المستخدم. يسرد كل إدخال اتصالات المستخدم:

presenceState()json
{
  "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() يزيلك من القائمة، وترك القناة أو إغلاق الصفحة يفعل ذلك نيابة عنك.

#
التغييرات

4. تغييرات قاعدة البيانات

المشاريع التي لها قاعدة بيانات خاصة بها

يعمل postgres_changes في المشاريع التي لها قاعدة بيانات خاصة بها. فعّل كل جدول أولًا: PUT /v1/db/{project_id}/schema/tables/{table}/realtime مع جسم الطلب {"enabled": true} ومفتاح service_role. يبدأ الاستماع عندما يشترك أول عميل ويتوقف بعد بضع دقائق من مغادرة آخر عميل. التسليم مرة واحدة على الأقل: بعد إعادة تشغيل الخادم قد يصل التغيير نفسه مرتين، لذا اجعل معالجك متساوي القوة (idempotent)، مثلًا بالاعتماد على المفتاح الأساسي للصف. قد ترفض مجموعة مشغولة مستمعًا جديدًا بخطأ في السعة؛ أعد المحاولة بعد قليل. سمِّ القناة باسم الجدول، db:public.<table>: على هذه القناة تُنشر التغييرات. قد يتلقى أول مشترك ما يصل إلى 5 ثوانٍ من التغييرات التي أُجريت قبيل اشتراكه. تُحفظ التغييرات ساعة واحدة لأغراض الاستئناف ثم تُحذف. عندما يكون العنقود ممتلئًا يفشل الاشتراك بالرسالة capacité d'écoute postgres_changes atteinte pour la base de ce projet, réessayez. إذا بقي الاستماع مفقودًا أكثر من دقيقة تنتقل القناة إلى CHANNEL_ERROR؛ اشترك من جديد بعد عودته. أي انقطاع أطول من ساعة الاحتفاظ يُفقد التغييرات التي أُجريت خلاله.

changes.tstypescript
const changes = aura.realtime
  .channel('db:public.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')
  })
#
تنظيف

5. تنظيف

cleanup.tstypescript
room.unsubscribe()                 // ترك قناة واحدة
aura.realtime.removeChannel(room)  // ترك وننسى ذلك
aura.realtime.removeAllChannels()  // اترك كل قناة
aura.realtime.disconnect()         // أغلق الاتصال

شاهد الاتصال مع aura.realtime.onStateChange(callback) و onError(callback). بعد انقطاع الاتصال، يقوم العميل بإعادة الاتصال بنفسه ما لم تتصل بـ setAutoReconnect(false).