كتلة Firebase - Firestore والمراسلة السحابية في روبوت المحادثة الخاص بك

نظرة عامة

تربط كتلة Firebase روبوت المحادثة في ChatMaxima مباشرةً بمشروع Firebase. تتيح لتدفقك قراءة وكتابة المستندات في Cloud Firestore وإرسال إشعارات دفع FCM إلى مستخدمي تطبيقك على الهاتف المحمول أو الويب، كل ذلك من كتلة واحدة. تعمل أي عملية تهيّئها عند النقطة الدقيقة في المحادثة التي تُسقط فيها الكتلة، بحيث يمكن لروبوتك سحب البيانات من Firestore، أو تخزين الحالة فيه، أو تشغيل إشعار دفع استجابةً لحالة محادثة معينة.

تشمل حالات الاستخدام النموذجية تخزين بيانات العملاء المحتملين في مجموعات Firestore الخاصة بك، والبحث عن ملف مستخدم مصادَق عليه بواسطة المعرّف، والتحقق من حالة الطلب أو الحجز من الواجهة الخلفية لتطبيقك، وإرسال إشعارات إلى أجهزة المستخدم عندما تصل المحادثة إلى مرحلة معيّنة (تأكيد الطلب، حجز الموعد، حل تذكرة الدعم). تتعامل الكتلة مع المصادقة وتخزين الرموز مؤقتاً وتوجيه الأخطاء تلقائياً، لذا ما عليك سوى اختيار عملية وملء الحقول المهمة لها.

المتطلبات المسبقة

قبل أن تضيف كتلة Firebase إلى تدفق، تأكد من توفر:

• مشروع Firebase مع تفعيل Cloud Firestore. قاعدة البيانات في الوقت الفعلي غير مدعومة في هذه الكتلة (الإصدار 1 يغطّي Firestore فقط).
• مفتاح JSON لحساب خدمة مُنزّل من مشروع Firebase الخاص بك. في وحدة تحكم Firebase اذهب إلى إعدادات المشروع، وافتح علامة تبويب حسابات الخدمة، وانقر على إنشاء مفتاح خاص جديد. احفظ ملف JSON المُنزّل. ستلصق محتوياته في ChatMaxima في الخطوة التالية.
• إعداد FCM على تطبيق العميل الخاص بك إذا كنت تخطط لإرسال إشعارات دفع. يجب تسجيل كل جهاز في Firebase وتخزين رمز تسجيل FCM الخاص به في مكان يمكن للروبوت جلبه منه (عادةً مصفوفة users/{user_id}.tokens في Firestore).

ملاحظة: مفتاح حساب الخدمة سرّ طويل الأمد. تعامل معه بالطريقة نفسها التي تتعامل بها مع كلمة مرور قاعدة بيانات الإنتاج. لا تودعه في إدارة المصادر أو تشاركه في الدردشة.

الخطوة 1: ربط Firebase كتكامل

1. اذهب إلى لوحة التحكم ← التكاملات وانقر على إضافة تكامل
2. اختر Firebase من القائمة المنسدلة للمنصات
3. أدخل اسماً (على سبيل المثال Production Firebase أو My App Firestore) لكي تتمكن من التعرف عليه لاحقاً
4. الصق المحتويات الكاملة لملف JSON لحساب الخدمة في حقل Service Account JSON
5. انقر على التحقق والحفظ

يتحقق ChatMaxima من بيانات الاعتماد عن طريق توقيع JWT بالمفتاح الخاص، واستبداله برمز وصول OAuth، وإجراء استدعاء اختباري لنقطة نهاية listCollectionIds في Firestore. إذا كان المشروع لديه Firestore مفعّلاً وحساب الخدمة لديه وصول، سترى تم ربط تكامل Firebase. التكامل الآن متاح لكل روبوت في فريقك.

ملاحظة: يُخزَّن رمز الوصول مؤقتاً داخل ChatMaxima ويُحدَّث تلقائياً قبل انتهاء صلاحيته. لا تحتاج إلى تدوير أو إعادة إدخال JSON لحساب الخدمة إلا إذا أردت الانتقال إلى مشروع Firebase مختلف.

الخطوة 2: إضافة كتلة Firebase إلى تدفق

1. افتح روبوت المحادثة الخاص بك في Studio
2. انقر بزر الماوس الأيمن على اللوحة (أو اسحب من الشريط الجانبي الأيسر) واختر Firebase ضمن التكاملات الخارجية
3. انقر نقراً مزدوجاً على الكتلة لفتح تهيئتها
4. اختر التكامل الذي أنشأته في الخطوة 1 من القائمة المنسدلة اختيار التكامل
5. اختر عملية واملأ الحقول الموضّحة أدناه

العمليات المتاحة

تدعم كتلة Firebase سبع عمليات. تعمل العمليات الست الأولى مع Cloud Firestore. ترسل العملية السابعة إشعار دفع عبر المراسلة السحابية (FCM).

العملية	الفئة	ما تفعله
جلب مستند	Firestore	يقرأ مستنداً واحداً حسب المجموعة ومعرّف المستند
إضافة مستند	Firestore	ينشئ مستنداً جديداً. ينشئ Firestore المعرّف تلقائياً إذا تركته فارغاً
ضبط مستند	Firestore	يستبدل المستند عند معرّف محدد. يستبدل جميع الحقول
تحديث مستند	Firestore	يدمج فقط الحقول التي تقدّمها في مستند موجود
حذف مستند	Firestore	يزيل مستنداً عند معرّف محدد
الاستعلام عن مجموعة	Firestore	يرشّح ويرتّب ويحدّ مجموعة من المستندات
إرسال إشعار	المراسلة السحابية	يرسل إشعاراً إلى جهاز واحد أو أجهزة عديدة أو موضوع

يدعم كل إدخال (المجموعة، معرّف المستند، قيم الحقول، رمز FCM، عنوان الإشعار، والنص) متغيرات ChatMaxima بصيغة {variable}، بحيث يمكنك ملؤها من كتل أسئلة سابقة، أو استدعاءات API سابقة، أو بيانات مستلمة في كتلة ويب هوك.

تهيئة العمليات

جلب مستند

يقرأ مستنداً واحداً حسب المعرّف. استخدم هذا للبحث عن ملف مستخدم، أو جلب الحالة الحالية لطلب، أو سحب أي سجل لديك معرّفه بالفعل.

الحقل	الوصف
المجموعة	اسم مجموعة Firestore (على سبيل المثال users أو orders). اختر من القائمة المكتشفة أو اكتب اسماً جديداً
معرّف المستند	المعرّف المراد قراءته. يدعم المتغيرات مثل {user_id}
تخزين الاستجابة في متغير	اسم متغير ChatMaxima الذي يحمل النتيجة

إضافة مستند

ينشئ مستنداً جديداً في مجموعة. اترك معرّف المستند فارغاً للسماح لـ Firestore بإنشائه تلقائياً، أو قدّم معرّفك الخاص (على سبيل المثال {lead_id}).

الحقل	الوصف
المجموعة	المجموعة المستهدفة
معرّف المستند (اختياري)	اتركه فارغاً للمعرّف التلقائي، أو قدّم معرّفاً مخصصاً
ربط الحقول	صفوف مفتاح/قيمة. المفاتيح هي أسماء حقول Firestore، والقيم يمكن أن تكون قيماً حرفية أو مراجع {variable}
تخزين الاستجابة في متغير	يُخزَّن المستند المحفوظ (مع معرّفه المُنشأ) هنا

ضبط مستند

يستبدل المستند عند collection/document_id بالحقول التي تسردها بالضبط. تُزال أي حقول كانت موجودة سابقاً على المستند ولكنها ليست في عملية الربط الخاصة بك. استخدم هذا عندما تريد استبدالاً نظيفاً بدلاً من الدمج.

تحديث مستند

يدمج فقط الحقول التي تقدّمها في مستند موجود. تُترك الحقول غير الموجودة في عملية الربط دون مساس. هذه هي عملية الكتابة الأكثر أماناً لتحديث ملف مستخدم أو سجل طلب بشكل تدريجي.

حذف مستند

يزيل المستند عند collection/document_id. سيحتوي متغير الاستجابة على {"success": true} إذا نجح الحذف.

الاستعلام عن مجموعة

يُشغّل استعلاماً منظماً في Firestore ضد مجموعة. يدعم المرشّحات والترتيب وحد الصفوف.

الحقل	الوصف
المجموعة	المجموعة المراد الاستعلام عنها
مرشّحات الاستعلام	صفوف من field وoperator وvalue. تُدمج بـ AND
حقل الترتيب حسب	اسم حقل اختياري للترتيب حسبه
اتجاه الترتيب	تصاعدي أو تنازلي
الحد	الحد الأقصى لعدد المستندات المراد إعادتها. اتركه فارغاً لعدم وجود حد

عوامل المرشّح المدعومة:

العامل	المعنى
EQUAL	الحقل يساوي القيمة
NOT_EQUAL	الحقل لا يساوي القيمة
LESS_THAN	الحقل أقل من القيمة
LESS_THAN_OR_EQUAL	الحقل أقل من أو يساوي القيمة
GREATER_THAN	الحقل أكبر من القيمة
GREATER_THAN_OR_EQUAL	الحقل أكبر من أو يساوي القيمة
ARRAY_CONTAINS	الحقل مصفوفة تحتوي على القيمة
IN	قيمة الحقل هي إحدى القيم المدرجة
ARRAY_CONTAINS_ANY	مصفوفة الحقل تحتوي على أي من القيم المدرجة
NOT_IN	قيمة الحقل ليست أياً من القيم المدرجة

إرسال إشعار

يرسل إشعار دفع FCM. اختر واحداً من ثلاثة أهداف:

الإرسال إلى	متى تستخدمه
جهاز واحد	رمز تسجيل FCM محدد واحد
أجهزة متعددة	إرسال متعدد إلى رموز عديدة في خطوة واحدة. يقبل متغيراً يُحلّ إلى مصفوفة JSON أو سلسلة مفصولة بفواصل أو مصفوفة أصلية
موضوع	بث إلى كل جهاز مشترك في موضوع (على سبيل المثال premium-users)

حقول التهيئة:

الحقل	الوصف
رمز / رموز / موضوع FCM	المستلم، اعتماداً على نوع الهدف. المتغيرات مدعومة
عنوان الإشعار	العنوان العريض المعروض في إشعار الدفع
نص الإشعار	نص الرسالة المعروض تحت العنوان
حمولة البيانات	أزواج مفتاح/قيمة اختيارية تُسلَّم بصمت إلى جانب الإشعار. مفيدة للربط العميق (على سبيل المثال screen=orders وorder_id={order_id}). تُحوَّل القيم إلى سلاسل نصية قبل الإرسال، وفقاً لقواعد FCM

تنسيق متغير الاستجابة

تخزّن كل عملية نتيجة JSON في المتغير الذي تسمّيه ضمن تخزين الاستجابة في متغير. يمكن للكتل اللاحقة الإشارة إلى الحقول باستخدام العلامة النقطية، على سبيل المثال {user_data.data.email}.

قراءات Firestore (جلب مستند)

{
  "id": "user_42",
  "name": "projects/my-project/databases/(default)/documents/users/user_42",
  "data": {
    "name": "Priya",
    "email": "priya@example.com",
    "tokens": ["iphone_tok", "ipad_tok"]
  },
  "create_time": "2026-04-20T10:30:00Z",
  "update_time": "2026-04-21T14:15:00Z"
}

كتابات Firestore (إضافة / ضبط / تحديث)

الشكل نفسه كـ جلب مستند. يعكس حقل id معرّف المستند النهائي (المُنشأ تلقائياً إذا لم تقدّم واحداً).

حذف Firestore

{ "success": true }

الاستعلام عن مجموعة

مصفوفة من كائنات المستندات، كل منها بالشكل أعلاه:

[
  { "id": "order_1", "data": { "status": "confirmed", "amount": 900 }, "create_time": "..." },
  { "id": "order_2", "data": { "status": "confirmed", "amount": 1200 }, "create_time": "..." }
]

إرسال إشعار (واحد / موضوع)

{
  "success": true,
  "message_name": "projects/my-project/messages/0:17045...",
  "target_type": "token",
  "target_value": "iphone_tok"
}

إرسال إشعار (متعدد)

{
  "success": true,
  "sent": 2,
  "failed": 1,
  "invalid_tokens": ["stale_tok"],
  "results": [
    { "token": "iphone_tok", "success": true, "message_name": "..." },
    { "token": "ipad_tok",   "success": true, "message_name": "..." },
    { "token": "stale_tok",  "success": false, "error": "Requested entity was not found.", "error_code": "UNREGISTERED" }
  ]
}

تسرد مصفوفة invalid_tokens الرموز التي وسمتها Firebase كقديمة (UNREGISTERED أو INVALID_ARGUMENT أو NOT_FOUND). استخدم كتلة Firebase تالية مع تحديث مستند لإزالتها من مجموعة users الخاصة بك في Firestore بحيث تتوقف عن استهداف الأجهزة الميتة.

حالات الاستخدام الشائعة

إشعار دفع لتأكيد الطلب

يكمل العميل الدفع داخل التطبيق، وتريد أن يرسل الروبوت تأكيداً إلى كل جهاز سجّله المستخدم.

1. كتلة سؤال: التقط أو تحقق من {user_id}
2. كتلة Firebase (جلب مستند): المجموعة users، معرّف المستند {user_id}، خزّن النتيجة في {user_data}
3. كتلة شرط: تفرّع على {order_status} == "confirmed"
4. كتلة Firebase (إرسال إشعار، أجهزة متعددة): الرموز {user_data.data.tokens}، العنوان Order confirmed، النص Hi {user_data.data.name}, your order {order_id} is on its way
5. كتلة رسالة: We have sent a confirmation to your devices

كتابة العملاء المحتملين من روبوت المحادثة إلى Firestore

استخدم Firestore كمصدر الحقيقة للعملاء المحتملين الواردين بحيث يمكن لتطبيق الهاتف المحمول الخاص بك التفاعل في الوقت الفعلي.

1. كتلة سؤال: اطلب {name} و{email} و{phone}
2. كتلة Firebase (إضافة مستند): المجموعة chatbot_leads، الحقول name={name} وemail={email} وphone={phone} وsource=chatbot
3. كتلة رسالة: Thanks {name}, we will be in touch shortly

التحقق من توفر الحجز

قبل تأكيد حجز، استعلم عن Firestore للتأكد من أن الفترة لا تزال متاحة.

1. كتلة Firebase (الاستعلام عن مجموعة): المجموعة bookings، المرشّح slot_id EQUAL {slot_id} وstatus NOT_EQUAL cancelled، الحد 1، خزّن في {existing_bookings}
2. كتلة شرط: تفرّع على ما إذا كان {existing_bookings} فارغاً
3. عند الفراغ: كتلة Firebase (إضافة مستند) لإنشاء الحجز، ثم كتلة رسالة للتأكيد
4. عند التطابق: كتلة رسالة That slot was just taken, please pick another

البث إلى موضوع

أرسل إعلاناً من واحد إلى كثير لكل جهاز مشترك في موضوع.

1. كتلة مُشغّل: يُشغّل المسؤول التدفق بحملة
2. كتلة Firebase (إرسال إشعار، موضوع): الموضوع premium-users، العنوان New feature released، النص Tap to try it out، البيانات screen=whats_new

تنظيف رموز FCM القديمة

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

1. كتلة Firebase (إرسال إشعار، أجهزة متعددة): خزّن النتيجة في {push_result}
2. كتلة شرط: تفرّع على ما إذا كان {push_result.invalid_tokens} غير فارغ
3. كتلة كود أو كتلة API: احسب قائمة الرموز المُنقّحة
4. كتلة Firebase (تحديث مستند): المجموعة users، معرّف المستند {user_id}، الحقل tokens={pruned_tokens}

أفضل الممارسات

• حدّد نطاق حساب الخدمة بشكل صحيح. أنشئ حساب خدمة مخصصاً لـ ChatMaxima وامنحه فقط أدوار Firestore وFCM التي يحتاجها. لا تستخدم مفتاح Admin SDK الافتراضي للإنتاج
• خزّن رموز FCM كمصفوفة. غالباً ما يملك المستخدمون أجهزة متعددة. إبقاؤها في حقل tokens واحد لكل مستخدم يجعل عمليات الإرسال المتعدد سهلة
• تعامل مع فرع الخطأ. لكل كتلة Firebase إخراج ثانٍ يُفعَّل عند فشل العملية. وجّهه إلى رسالة استرداد أو إعادة محاولة، بدلاً من ترك التدفق يتوقف
• نقّح الرموز القديمة. يعيد FCM رمز UNREGISTERED عندما يكون الرمز ميتاً. استخدم حقل invalid_tokens في استجابة الإرسال المتعدد لتنظيف ملفات المستخدمين الخاصة بك
• أبقِ قيم حمولة البيانات صغيرة. يتطلب FCM أن تكون جميع قيم حمولة البيانات سلاسل نصية وأن يبقى حجم الرسالة الإجمالي تحت 4 كيلوبايت. يحوّل ChatMaxima القيم إلى سلاسل تلقائياً، لكن كتل JSON الكبيرة سترفضها Firebase
• لا تسرّب JSON لحساب الخدمة. بمجرد الحفظ في ChatMaxima، لا يُعرض JSON مرة أخرى في الواجهة. تعامل مع الملف المُنزّل بالعناية نفسها كأي سرّ إنتاج آخر

الأسئلة المتكررة

ما منتجات Firebase التي تدعمها الكتلة؟

Cloud Firestore (قراءة / كتابة / استعلام) والمراسلة السحابية (واجهة FCM HTTP v1). قاعدة البيانات في الوقت الفعلي ومصادقة Firebase ووظائف السحابة والمراسلة داخل التطبيق غير مُعالَجة بواسطة هذه الكتلة.

هل يمكنني استخدام الكتلة نفسها لكلٍّ من Firestore وFCM؟

نعم. تفوّض بيانات اعتماد تكامل Firebase واحدة كلا المنتجين. أسقط كتل Firebase منفصلة لكل عملية تحتاجها (على سبيل المثال، كتلة جلب مستند واحدة للبحث عن رموز المستخدم، ثم كتلة إرسال إشعار واحدة للدفع إلى تلك الرموز).

أين يُخزَّن JSON لحساب الخدمة الخاص بي؟

داخل جدول chatbot_integration_tokens، محدد النطاق لفريقك. لا يُعاد JSON إلى المتصفح بعد الحفظ أبداً. يستخدمه ChatMaxima على جانب الخادم لإنشاء رموز وصول OAuth قصيرة الأمد لـ Firebase.

لماذا يصل الإشعار لكن حمولة البيانات مفقودة؟

يتطلب FCM أن تكون قيم حمولة البيانات سلاسل نصية. إذا مرّرت متغيراً رقمياً أو منطقياً مباشرةً، يحوّله ChatMaxima إلى سلسلة من أجلك، لكن بعض تطبيقات العملاء تتوقع تنسيقات محددة. تحقق مرتين من كيفية قراءة تطبيقك لـ RemoteMessage.getData() على Android أو userInfo على iOS.

يُظهر إرسالي المتعدد فشل بعض الرموز. ماذا أفعل؟

انظر إلى مصفوفة invalid_tokens في متغير الاستجابة. هذه رموز تعتبرها Firebase ميتة. استخدم كتلة تحديث مستند لإزالتها من مصفوفة tokens للمستخدم في Firestore بحيث لا تُستهدف مجدداً.

هل يمكن للكتلة الإرسال إلى معرّف مستخدم بدلاً من رمز FCM؟

ليس مباشرةً. يخاطب FCM الأجهزة برمز التسجيل، وليس بالمستخدم. النمط المعتاد هو: تخزين رموز المستخدم في Firestore ضمن users/{user_id}، واستخدام كتلة جلب مستند لجلبها، ثم تمرير مصفوفة الرموز إلى كتلة إرسال الإشعار.

هل يمكنني الاستعلام عن المجموعات الفرعية؟

تستعلم الكتلة الحالية عن المجموعات عالية المستوى. استعلامات المجموعات المتداخلة أو الفرعية (على سبيل المثال users/{uid}/orders) موجودة على خارطة الطريق. كحل بديل، خزّن بيانات غير منظمة في مجموعة عالية المستوى مفتاحها معرّف المستخدم.

كيف أختبر الكتلة قبل التشغيل المباشر؟

أنشئ مشروع Firebase تجريبي مع بضعة مستندات اختبار. اربطه كتكامل ChatMaxima منفصل، ووجّه الكتلة إليه، وشغّل التدفق من وضع المعاينة في Studio. بدّل الكتلة إلى تكامل الإنتاج بمجرد أن تكون راضياً.

استكشاف الأخطاء وإصلاحها

يفشل التحقق والحفظ بـ "رُفضت بيانات الاعتماد من قبل Firestore"

1. افتح مشروع Firebase الخاص بك وتأكد من تفعيل Cloud Firestore (وحدة التحكم ← قاعدة بيانات Firestore)
2. تحقق من أن حساب الخدمة لديه على الأقل دور Cloud Datastore User (IAM ← حسابات الخدمة)
3. تأكد من لصق ملف JSON بأكمله، بما في ذلك حقل private_key مع تسلسلات هروب السطر الجديد \n سليمة
4. أعد إنشاء المفتاح الخاص إذا كان الملف الأصلي قد عُدّل أو نُسخ جزئياً

تُظهر الكتلة "لم يُعثر على تكامل Firebase"

1. تأكد من وجود التكامل ضمن لوحة التحكم ← التكاملات وأنه نشط
2. إذا أنشأت التكامل مؤخراً، حدّث نافذة الكتلة باستخدام زر التحديث بجوار القائمة المنسدلة للتكامل
3. احذف التكامل وأعد إنشاءه إذا دُوّرت بيانات الاعتماد في Firebase

يعيد Firestore "المستند غير موجود" (404)

1. تحقق من أن اسم المجموعة مكتوب تماماً كما يظهر في Firebase (حساس لحالة الأحرف)
2. تحقق من معرّف المستند. إذا أتى من متغير، افحص سجل المحادثة لرؤية القيمة الفعلية المُستبدلة
3. تذكّر أن Firestore يعامل مستنداً مفقوداً بشكل مختلف عن مستند فارغ. تعيد الكتلة not_found: true في متغير الاستجابة بحيث يمكنك التفرّع عليه

لا يصل إشعار FCM إلى الجهاز

1. تأكد من أن رمز FCM صالح. تنتهي صلاحية الرموز عند إلغاء تثبيت التطبيق أو إعادة تثبيته
2. تحقق من أن الجهاز لديه أذونات الإشعارات الممنوحة لتطبيقك
3. افحص متغير الاستجابة. يعيد الإرسال الناجح message_name. يعيد الفشل error وغالباً error_code مثل UNREGISTERED
4. تحقق من أن الجهاز ليس في وضع توفير البطارية أو محظوراً بواسطة وضع "عدم الإزعاج" على مستوى النظام

ينجح إرسال الموضوع لكن لا أحد يستقبله

1. تسليم الموضوع هو أفضل جهد وقد يستغرق حتى دقيقة
2. تأكد من أن الأجهزة قد اشتركت فعلياً في الموضوع (messaging().subscribeToTopic('premium-users') على العميل)
3. أسماء المواضيع حساسة لحالة الأحرف ولا يمكن أن تبدأ بـ /topics/ في واجهة الإصدار 1. استخدم الاسم فقط، على سبيل المثال premium-users

متغير الاستجابة فارغ

1. تأكد من ملء حقل تخزين الاستجابة في متغير على الكتلة
2. تحقق من أن اسم المتغير لا يتعارض مع كلمة محجوزة أو متغير كتلة أخرى
3. افحص سجل المحادثة لرؤية النتيجة الخام لاستدعاء Firebase

الخطوات التالية

• كتلة API - استدعِ أي واجهة برمجة تطبيقات REST خارجية من تدفقك
• كتلة الويب هوك - استقبال استدعاءات HTTP واردة في تدفقك
• كتلة الشرط - تفرّع التدفق على قيم المتغيرات
• نظرة عامة على Studio - استكشف جميع أنواع الكتل وميزات مُنشئ التدفق