تخطّ إلى المحتوى الرئيسي

الحصول على بيانات اعتماد Firebase (FCM) (Android)

يرسل Joryio إشعارات Push إلى أجهزة Android عبر Firebase Cloud Messaging (FCM)، باستخدام FCM HTTP v1 API. ولذلك يحتاج إلى مفتاح حساب خدمة (service account) من مشروع Firebase الذي يستخدمه تطبيق Android الخاص بك. تشرح هذه الصفحة خطوة بخطوة إعداد Firebase وإنشاء المفتاح وإدخاله في Joryio.

لكل تطبيق في Joryio بيانات اعتماد Push خاصة به، لذا تُجري هذه الخطوات مرة واحدة لكل تطبيق Android. لمشروع React Native أو Unity تطبيق Android منفصل في Joryio، وتُدخل بيانات اعتماد FCM الخاصة به هناك. راجع التتبع متعدد المنصات.

ما يطلبه Joryio​

الحقل في Joryioما هوإلزامي
Firebase service account (JSON)ملف المفتاح الخاص لحساب خدمة في مشروع Firebase الخاص بك. يرسل Joryio به كل Push إلى Android.نعم
Sender IDمعرّف رقمي لمشروع Firebase. يحفظه Joryio لكنه لا يستخدمه في الإرسال.لا - يمكن تركه فارغًا

يدعم Joryio ملف JSON لحساب الخدمة فقط (FCM HTTP v1). «مفتاح الخادم» (server key) القديم في FCM غير مدعوم؛ فقد أوقفت Google واجهات FCM القديمة، ويفشل الإرسال من تطبيق Android لا يملك إلا مفتاح خادم.

لا تُرسل أجهزة iOS عبر Firebase: يرسل Joryio إلى iOS مباشرة عبر APNs. راجع الحصول على بيانات اعتماد APNs.

قبل أن تبدأ​

  • مشروع Firebase. أنشئ مشروعًا في Firebase console إذا لم يكن لديك مشروع.
  • إذن إنشاء مفاتيح حسابات الخدمة في ذلك المشروع. يمنح Google Cloud هذا الإذن عبر دور Service Account Key Admin، roles/iam.serviceAccountKeyAdmin، ويملكه مالكو المشروع (Owner) عادةً. إذا كانت مؤسستك في Google Cloud تفرض سياسة iam.disableServiceAccountKeyCreation، فإن إنشاء المفاتيح محظور؛ وتُفرض هذه السياسة افتراضيًا على المؤسسات التي أُنشئت في 3 مايو 2024 أو بعده. اطلب من مسؤول Google Cloud استثناء المشروع.
  • تطبيق Android في Joryio مدمج فيه Android SDK. لإنشاء تطبيق، راجع إنشاء التطبيقات.

الخطوة 1: إضافة تطبيق Android إلى Firebase​

يحتاج التطبيق إلى Firebase لكي تحصل الأجهزة على رمز تسجيل FCM. تخطَّ هذه الخطوة إذا كان تطبيقك يستخدم Firebase بالفعل.

  1. في Firebase console، افتح مشروعك.
  2. في صفحة نظرة عامة على المشروع، انقر أيقونة Android أو Add app.
  3. أدخل Android package name لتطبيقك، أي applicationId في ملف Gradle على مستوى الوحدة. وهو حساس لحالة الأحرف ولا يمكن تغييره بعد التسجيل.
  4. انقر Register app.
  5. انقر Download google-services.json وانقل الملف إلى المجلد الجذر لوحدة التطبيق، عادةً app/.
  6. أضف مكوّن Gradle الإضافي لخدمات Google، كما يعرضه Firebase console:
    • في ملف Gradle على مستوى الجذر: id("com.google.gms.google-services") version "<version>" apply false
    • في ملف Gradle على مستوى الوحدة (app): id("com.google.gms.google-services")
  7. أكمل إعداد Push في التطبيق كما هو موضح في قسم Push في Android SDK.

يحتوي google-services.json على معرّفات لتطبيقك وليس على أسرار، ويُضمَّن داخل التطبيق. وهو ليس الملف الذي يحتاجه Joryio؛ فالملف المطلوب هو مفتاح حساب الخدمة في الخطوة التالية.

الخطوة 2: إنشاء مفتاح حساب الخدمة​

  1. في Firebase console، انقر أيقونة الترس (Settings)، وافتح Project settings، ثم تبويب Service accounts.
  2. انقر Generate New Private Key، ثم أكّد بالنقر على Generate Key.
  3. يُنزَّل ملف JSON. احفظه بأمان؛ لا يمكنك تنزيل ملف المفتاح نفسه مرة أخرى. إذا فقدته، فأنشئ مفتاحًا جديدًا.

يحتوي الملف، ضمن حقول أخرى، على "type": "service_account" وproject_id وprivate_key وclient_email.

الخطوة 3: إدخال بيانات الاعتماد في Joryio​

  1. في لوحة تحكم Joryio، انتقل إلى الإعدادات → التطبيقات.
  2. اعثر على تطبيق Android في القائمة وانقر أيقونة إشعارات Push (الجرس) في صفه. تُفتح صفحة إشعارات Push - [اسم التطبيق].
  3. في بطاقة Firebase Cloud Messaging، انقر Upload service account JSON واختر الملف من الخطوة 2. يعرض Joryio أسفل الزر معرّف المشروع الذي قرأه من الملف. تحقق من أنه المشروع نفسه الموجود في project_id داخل google-services.json الخاص بتطبيقك.
  4. اختياري: أدخل Sender ID. لا يستخدمه Joryio في الإرسال، لذا يمكنك تركه فارغًا.
  5. انقر حفظ الإعداد.

تعرض قائمة التطبيقات الآن تم ضبط FCM أسفل اسم التطبيق. يُشفَّر حساب الخدمة عند التخزين ولا يُعرض مرة أخرى: عند إعادة فتح الصفحة تظهر الملاحظة «مضبوط - اتركه فارغًا للاحتفاظ بالقيمة الحالية، أو أدخل قيمة جديدة لاستبدالها.» لا ترفع ملفًا إلا إذا أردت استبدال الملف المحفوظ.

الخطوة 4: إرسال Push تجريبي​

  1. ثبّت تطبيقك على جهاز أو محاكي يحتوي على Google Play services، وافتحه، واسمح بالإشعارات (يطلب Android 13 والإصدارات الأحدث إذن الإشعارات). يسجّل SDK رمز FCM للجهاز في Joryio.
  2. أنشئ حملة Push، أو افتح مسودة، ترسل من هذا التطبيق.
  3. انقر إرسال Push تجريبي في المتغير، واختر المستخدم المسجّل الدخول على جهازك، ثم أرسل.

إذا فشل الاختبار، تتضمن رسالة الخطأ السبب الذي أعاده FCM؛ ابحث عنه في الجدول أدناه. لمسار الحملة الكامل، راجع إشعارات Push.

الأخطاء الشائعة وحلولها​

ما تراهالسبب المحتملالحل
«That does not look like a Firebase service account JSON (missing project_id / private_key / client_email).»الملف المرفوع ليس مفتاح حساب خدمة؛ وغالبًا ما يكون google-services.json.ارفع الملف من Project settings → Service accounts → Generate New Private Key، الخطوة 2.
«Could not parse that file as JSON.»الملف تالف أو ليس JSON.أنشئ مفتاحًا جديدًا وارفع الملف الجديد دون تعديل.
«FCM not configured: this app needs a Firebase service account (the legacy server key is no longer supported)»لا يوجد حساب خدمة محفوظ للتطبيق؛ مثلًا لديه مفتاح خادم قديم فقط.ارفع ملف JSON لحساب خدمة واحفظ.
«Device token sender mismatch» (messaging/mismatched-credential أو messaging/sender-id-mismatch)صدر رمز الجهاز لمشروع Firebase مختلف عن مشروع حساب الخدمة.استخدم حساب خدمة من المشروع نفسه الخاص بملف google-services.json في إصدار تطبيقك، ثم افتح التطبيق على الجهاز مرة أخرى ليسجّل رمزه من جديد.
«Device token unregistered» (messaging/registration-token-not-registered)أُزيل التطبيق أو لم يعد الرمز صالحًا.لا يلزم إصلاح بيانات الاعتماد. يتوقف Joryio عن الإرسال إلى هذا الرمز.
أخطاء مصادقة أو أذوناتحُذف المفتاح أو عُطّل في Google Cloud، أو فقد حساب الخدمة أذوناته.أنشئ مفتاحًا جديدًا في Firebase وارفعه.
«no device accepted the notification»ليس لدى المستخدم جهاز Android مسجّل لهذا التطبيق.افتح التطبيق المدمج فيه SDK على الجهاز، واسمح بالإشعارات، وتأكد من أنك تختبر بالمستخدم نفسه.

الأمان وتدوير المفاتيح​

  • تعامل مع ملف JSON لحساب الخدمة كسر: فهو يحتوي على مفتاح خاص يمكنه إرسال رسائل إلى مستخدمي تطبيقك واستدعاء واجهات Google الأخرى المسموح بها لحساب الخدمة. لا تضفه إلى نظام التحكم في الإصدارات، ولا ترسله بالبريد الإلكتروني أو الدردشة، ولا تضمّنه داخل تطبيقك.
  • إذا كنت تعتقد أن المفتاح تسرّب، فأنشئ مفتاحًا جديدًا، وارفعه في Joryio، ثم احذف المفتاح القديم في Google Cloud console: IAM & Admin → Service accounts، وانقر حساب الخدمة، وافتح تبويب Keys، واحذف المفتاح القديم. لا يمكن استعادة مفتاح محذوف.
  • لتدوير المفتاح دون انقطاع، اتبع الترتيب نفسه: المفتاح الجديد في Joryio أولًا، ثم حذف القديم.