إضافة Firebase إلى مشروع Android

المتطلبات الأساسية

• ثبِّت Android Studio أو عدِّله إلى أحدث إصدار.

• تأكَّد من أنّ مشروعك يستوفي هذه المتطلبات (يُرجى العِلم أنّ بعض المنتجات قد تفرض متطلبات أكثر صرامة):

  • استهداف المستوى 21 من واجهة برمجة التطبيقات (Lollipop) أو إصدار أحدث
  • يعمل بالإصدار 5.0 من Android أو إصدار أحدث
  • استخدام Jetpack (AndroidX)، بما في ذلك استيفاء متطلبات الإصدارات التالية:
    • com.android.tools.build:gradle الإصدار 7.3.0 أو الإصدارات الأحدث
    • compileSdkVersion 28 أو إصدار أحدث

• يمكنك إعداد جهاز فعلي أو استخدام محاكي لمحاولة تشغيل تطبيقك.
  يُرجى العِلم أنّ حِزم تطوير البرامج (SDK) لـ Firebase التي تعتمد على "خدمات Google Play" تتطلّب تثبيت "خدمات Google Play" على الجهاز أو المحاكي.

• سجِّل الدخول إلى Firebase باستخدام حسابك على Google.

إذا لم يكن لديك مشروع على Android وأردت تجربة أحد منتجات Firebase، يمكنك تنزيل أحد عيّنات البدء السريع.

يمكنك ربط تطبيق Android بمنصّة Firebase باستخدام أحد الخطوات التالية:

• الخيار 1: (يُنصح به) استخدام سير عمل إعداد وحدة تحكّم Firebase.
• الخيار 2: استخدام "مساعِد Firebase" في Android Studio (قد يتطلّب ذلك إجراء إعدادات إضافية).

---

الخيار 1: إضافة Firebase باستخدام وحدة تحكُّم Firebase

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

الخطوة 1: إنشاء مشروع على Firebase

قبل أن تتمكّن من إضافة Firebase إلى تطبيق Android، عليك إنشاء مشروع على Firebase للربط بتطبيق Android. يُرجى الانتقال إلى مقالة فهم مشاريع Firebase للاطّلاع على مزيد من المعلومات عن مشاريع Firebase.

إنشاء مشروع على Firebase

1. في وحدة تحكّم Firebase، انقر على إضافة مشروع.

   • لإضافة موارد Firebase إلى مشروع Google Cloud حالي، أدخِل اسم المشروع أو اختَره من القائمة المنسدلة.

   • لإنشاء مشروع جديد، أدخِل اسم المشروع المطلوب. يمكنك أيضًا اختياريًا تعديل رقم تعريف المشروع المعروض أسفل اسم المشروع.

2. راجِع بنود Firebase واقبلها إذا طُلب منك ذلك.

3. انقر على متابعة.

4. (اختياري) يمكنك إعداد Google Analytics لمشروعك، ما يتيح لك الحصول على تجربة مثالية باستخدام أيّ من منتجات Firebase التالية:

   Firebase Crashlytics Firebase Cloud Messaging

   Firebase In-App Messaging Firebase Remote Config

   Remote Config التخصيص Firebase A/B Testing

   اختَر إما حساب Google Analytics حاليًا أو أنشئ حسابًا جديدًا.

   إذا أنشأت حسابًا جديدًا، اختَر Analytics الموقع الجغرافي لإعداد التقارير، ثم وافِق على إعدادات مشاركة البيانات وبنود Google Analytics لمشروعك.

5. انقر على إنشاء مشروع (أو إضافة Firebase، إذا كنت تستخدم مشروعًا حاليًا على Google Cloud).

توفّر Firebase الموارد تلقائيًا لمشروعك على Firebase. عند اكتمال العملية، سيتم نقلك إلى صفحة النظرة العامة لمشروع Firebase في وحدة تحكّم Firebase.

الخطوة 2: تسجيل تطبيقك في Firebase

لاستخدام Firebase في تطبيق Android، عليك تسجيل تطبيقك في مشروعك على Firebase. غالبًا ما يُشار إلى عملية تسجيل تطبيقك باسم "إضافة" تطبيقك إلى مشروعك.

1. انتقِل إلى وحدة تحكّم Firebase.

2. في وسط صفحة النظرة العامة على المشروع، انقر على رمز Android (plat_android) أو إضافة تطبيق لبدء سير عمل الإعداد.

3. أدخِل اسم حزمة تطبيقك في حقل اسم حزمة Android.

   ما هو اسم الحزمة، وأين يمكن العثور عليه؟

   • يحدِّد اسم الحزمة تطبيقك بشكلٍ فريد على الجهاز وفي "متجر Google Play".

   • يُشار إلى اسم الحزمة غالبًا باسم رقم تعريف التطبيق.

   • ابحث عن اسم حزمة تطبيقك في ملف Gradle للوحدة (على مستوى التطبيق)، وهو عادةً app/build.gradle (مثال على اسم الحزمة: com.yourcompany.yourproject).

   • يُرجى العِلم أنّ قيمة اسم الحزمة حسّاسة لحالة الأحرف، ولا يمكن تغييرها لتطبيق Firebase هذا على Android بعد تسجيله في مشروعك على Firebase.

4. (اختياري) أدخِل معلومات التطبيق الأخرى: اسم التطبيق المعرِّف وشهادة توقيع تصحيح الأخطاء بتنسيق SHA-1.

   كيف يتم استخدام اسم التطبيق المعرِّف وشهادة توقيع تصحيح الأخطاء بتنسيق SHA-1 ضمن Firebase؟

   • الاسم المعرِّف للتطبيق: هو معرّف داخلي لتسهيل الاستخدام لا يظهر إلا لك في وحدة تحكّم Firebase.

   • شهادة توقيع تصحيح الأخطاء بتنسيق SHA-1: يجب أن تتضمّن تجزئة SHA-1 Firebase Authentication (عند استخدام تسجيل الدخول باستخدام حساب Google أو تسجيل الدخول باستخدام رقم الهاتف) و Firebase Dynamic Links.

5. انقر على تسجيل التطبيق.

الخطوة 3: إضافة ملف إعدادات Firebase

1. نزِّل ملف إعدادات Firebase لنظام التشغيل Android (google-services.json) ثم أضِفه إلى تطبيقك:

   1. انقر على تنزيل google-services.json للحصول على ملف إعدادات Firebase لنظام Android.

   2. انقِل ملف الإعدادات إلى الدليل الجذري للوحدة (على مستوى التطبيق) في تطبيقك.

   ما الذي يجب معرفته عن ملف الإعدادات هذا؟

   • يحتوي ملف إعدادات Firebase على معرّفات فريدة، ولكنها غير سرية لمشروعك. لمعرفة المزيد من المعلومات عن ملف الإعدادات هذا، يُرجى الانتقال إلى مقالة فهم مشاريع Firebase.

   • يمكنك تنزيل ملف إعداد Firebase مجددًا في أي وقت.

   • تأكَّد من عدم إلحاق اسم ملف الإعدادات بأحرف إضافية، مثل (2).

2. للسماح لحِزم تطوير البرامج (SDK) لمنصّة Firebase بالوصول إلى القيم في ملف الإعدادات google-services.json، تحتاج إلى مكوّن Google services Gradle الإضافي (google-services).

   1. في ملف Gradle على مستوى الجذر (على مستوى المشروع) (<project>/build.gradle.kts أو <project>/build.gradle)، أضِف المكوّن الإضافي لخدمات Google كعنصر تابع:

      Kotlin

      plugins {
        id("com.android.application") version "7.3.0" apply false
        // ...
      
        // Add the dependency for the Google services Gradle plugin
        id("com.google.gms.google-services") version "4.4.2" apply false
      }

      Groovy

      plugins {
        id 'com.android.application' version '7.3.0' apply false
        // ...
      
        // Add the dependency for the Google services Gradle plugin
        id 'com.google.gms.google-services' version '4.4.2' apply false
      }

   2. في ملف Gradle الخاص بالوحدة (على مستوى التطبيق) (عادةً <project>/<app-module>/build.gradle.kts أو <project>/<app-module>/build.gradle)، أضِف المكوّن الإضافي لخدمات Google:

      Kotlin

      plugins {
        id("com.android.application")
      
        // Add the Google services Gradle plugin
        id("com.google.gms.google-services")
        // ...
      }

      Groovy

      plugins {
        id 'com.android.application'
      
        // Add the Google services Gradle plugin
        id 'com.google.gms.google-services'
        // ...
      }

الخطوة 4: إضافة حِزم تطوير البرامج (SDK) لمنصّة Firebase إلى تطبيقك

1. في ملف Gradle للوحدة (على مستوى التطبيق) (عادةً <project>/<app-module>/build.gradle.kts أو <project>/<app-module>/build.gradle)، أضِف الملحقات ل منتجات Firebase التي تريد استخدامها في تطبيقك. ننصحك باستخدام Firebase Android BoM للتحكّم في إصدارات المكتبة.

   تم تفعيل Analytics

   dependencies {
     // ...
   
     // Import the Firebase BoM
     implementation(platform("com.google.firebase:firebase-bom:33.7.0"))
   
     // When using the BoM, you don't specify versions in Firebase library dependencies
   
     // Add the dependency for the Firebase SDK for Google Analytics
     implementation("com.google.firebase:firebase-analytics")
   
     // TODO: Add the dependencies for any other Firebase products you want to use
     // See https://firebase.google.com/docs/android/setup#available-libraries
     // For example, add the dependencies for Firebase Authentication and Cloud Firestore
     implementation("com.google.firebase:firebase-auth")
     implementation("com.google.firebase:firebase-firestore")
   }

   باستخدام ملف برمجي Firebase Android BoM، سيستخدم تطبيقك دائمًا إصدارات متوافقة من مكتبات Firebase لنظام التشغيل Android.

   هل تبحث عن وحدة مكتبة خاصة بلغة Kotlin؟ اعتبارًا من تشرين الأول (أكتوبر) 2023 (Firebase BoM 32.5.0)، يمكن لمطوّري Kotlin وJava الاعتماد على وحدة المكتبة الرئيسية (للاطّلاع على التفاصيل، راجِع الأسئلة الشائعة حول هذه المبادرة).

   لم يتم تفعيل Analytics

   dependencies {
     // ...
   
     // Import the Firebase BoM
     implementation(platform("com.google.firebase:firebase-bom:33.7.0"))
   
     // When using the BoM, you don't specify versions in Firebase library dependencies
   
     // TODO: Add the dependencies for Firebase products you want to use
     // See https://firebase.google.com/docs/android/setup#available-libraries
     // For example, add the dependencies for Firebase Authentication and Cloud Firestore
     implementation("com.google.firebase:firebase-auth")
     implementation("com.google.firebase:firebase-firestore")
   }

   باستخدام ملف برمجي Firebase Android BoM، سيستخدم تطبيقك دائمًا إصدارات متوافقة من مكتبات Firebase لنظام التشغيل Android.

   هل تبحث عن وحدة مكتبة خاصة بلغة Kotlin؟ اعتبارًا من تشرين الأول (أكتوبر) 2023 (Firebase BoM 32.5.0)، يمكن لمطوّري Kotlin وJava الاعتماد على وحدة المكتبة الرئيسية (للاطّلاع على التفاصيل، راجِع الأسئلة الشائعة حول هذه المبادرة).

2. بعد إضافة الملحقات للمنتجات التي تريد استخدامها، يمكنك مزامنة مشروع Android مع ملفات Gradle.

   هل تظهر لك رسالة خطأ في عملية الإنشاء بشأن دعم invoke-custom وتفعيل desugaring؟ في ما يلي كيفية حلّ هذه المشكلة.

   يجب تفعيل استخدام Java 8 في عمليات إنشاء Gradle التي تستخدم الإصدار 4.2 من المكوّن الإضافي لنظام Gradle المتوافق مع Android (AGP) أو الإصدارات الأقدم. بخلاف ذلك، ستتعذّر عملية إنشاء مشاريع Android هذه عند إضافة حزمة تطوير برامج Firebase.

   لحلّ مشكلة تعذُّر إنشاء التطبيق، يمكنك اتّباع أحد الخيارَين التاليَين:

   • أضِف compileOptions المدرَج في رسالة الخطأ إلى ملفbuild.gradle.kts أو build.gradle على مستوى التطبيق.
   • عليك زيادة minSdk لمشروع Android إلى 26 أو إصدار أحدث.

   يمكنك الاطّلاع على مزيد من المعلومات حول تعذُّر إنشاء الإصدار في هذه الأسئلة الشائعة.

وهذا كل ما في الأمر! يمكنك المتابعة للاطّلاع على الخطوات التالية المقترَحة.

إذا كنت تواجه مشكلة في الإعداد، يُرجى الانتقال إلى مقالة الأسئلة الشائعة وتحديد المشاكل وحلّها في Android.

---

الخيار 2: إضافة Firebase باستخدام مساعِد Firebase

يسجِّل مساعِد Firebase تطبيقك في مشروع على Firebase ويضيف ملفات Firebase ومكوناتها الإضافية والتبعيات اللازمة إلى مشروع Android، وكل ذلك من داخل Android Studio.

1. افتح مشروع Android في "استوديو Android"، ثم تأكَّد من استخدام أحدث إصدارَين من "استوديو Android" و"مساعِد Firebase":

   • نظام التشغيل Windows / Linux: المساعدة > البحث عن تحديثات
   • نظام التشغيل macOS: Android Studio > البحث عن التحديثات

2. افتح مساعِد Firebase: الأدوات > Firebase.

3. في لوحة مساعِد، اختَر منتجًا من Firebase لإضافته إلى تطبيقك. وسِّع قسمه، ثم انقر على رابط البرنامج التعليمي (على سبيل المثال، Analytics > تسجيل حدث في "إحصاءات Google").

   1. انقر على الربط بـ Firebase لربط مشروع Android بـ Firebase.

      ما هي وظيفة سير العمل هذا؟

      • ينشئ سير العمل هذا تلقائيًا تطبيق Android جديدًا على Firebase باستخدام اسم حزمة تطبيقك. يمكنك إنشاء تطبيق Android جديد على Firebase في أحد مشاريع Firebase الحالية أو مشروع جديد.

        في ما يلي بعض النصائح حول إعداد مشروعك على Firebase:

        • اطّلِع على أفضل الممارسات لإضافة تطبيقات إلى مشروع على Firebase، بما في ذلك كيفية التعامل مع الصيغ المتعددة.

        • في حال إنشاء مشروع جديد، ننصحك بشدة بإعداد Google Analytics لمشروعك، ما يتيح لك الاستفادة من تجربة مثالية باستخدام العديد من منتجات Firebase.

      • يضيف سير العمل هذا أيضًا ملف إعدادات Android (google-services.json) لمشروعك على Firebase إلى دليل الوحدات (على مستوى التطبيق) في تطبيقك.

   2. انقر على الزرّ لإضافة منتج Firebase المطلوب (على سبيل المثال، إضافة Analytics إلى تطبيقك).

4. مزامنة تطبيقك للتأكّد من توفّر الإصدارات اللازمة لجميع التبعيات

5. في لوحة مساعِد، اتّبِع تعليمات الإعداد المتبقية لمنتجات Firebase التي اختَرتها.

6. يمكنك إضافة أي عدد تريده من منتجات Firebase الأخرى من خلال "مساعِد Firebase".

وهذا كل ما في الأمر! احرص على الاطّلاع على الخطوات التالية المقترَحة.

إذا كنت تواجه مشكلة في الإعداد، يُرجى الانتقال إلى مقالة الأسئلة الشائعة وتحديد المشاكل وحلّها في Android.

---

المكتبات المتاحة

يسرد هذا القسم منتجات Firebase المتوافقة مع Android وتبعيات Gradle. اطّلِع على مزيد من المعلومات عن مكتبات Firebase لنظام التشغيل Android التالية:

• المستندات المرجعية (Kotlin | Java)

• حزمة تطوير البرامج (SDK) لمنصة Firebase لنظام التشغيل Android مستودع GitHub

يُرجى العلم أنّه عند استخدام العنصر Firebase Android BoM، لا تحدِّد إصدارات مكتبة فردية عند تحديد تبعيات مكتبة Firebase في ملف إعدادات إنشاء Gradle.

الخدمة أو المنتج	تبعية Gradle	أحدث إصدار من	هل تريد إضافة Analytics؟
Firebase Android BoM (Bill of Materials)	com.google.firebase:firebase-bom يحتوي أحدث إصدار من Firebase BoM على أحدث الإصدارات من كل مكتبة Firebase لنظام التشغيل Android. لمعرفة إصدارات المكتبة التي تم ربطها بإصدار BoM معيّن، راجِع ملاحظات الإصدار لهذا الإصدار من BoM.	33.7.0
AdMob	com.google.android.gms:play-services-ads	23.6.0
Analytics	com.google.firebase:firebase-analytics	22.1.2
App Check مزوّد بيانات مخصّص	com.google.firebase:firebase-appcheck	18.0.0
مزوّد تصحيح أخطاء App Check	com.google.firebase:firebase-appcheck-debug	18.0.0
App Check مقدّم خدمة Play Integrity	com.google.firebase:firebase-appcheck-playintegrity	18.0.0
App Distribution	com.google.firebase:firebase-appdistribution	16.0.0-beta14
App Distribution API	com.google.firebase:firebase-appdistribution-api	16.0.0-beta14
المكوّن الإضافي App Distribution	com.google.firebase:firebase-appdistribution-gradle	5.0.0
Authentication	com.google.firebase:firebase-auth	23.1.0
Cloud Firestore	com.google.firebase:firebase-firestore	25.1.1
Cloud Functions for Firebase Client SDK	com.google.firebase:firebase-functions	21.1.0
Cloud Messaging	com.google.firebase:firebase-messaging	24.1.0
Cloud Storage	com.google.firebase:firebase-storage	21.0.1
Crashlytics	com.google.firebase:firebase-crashlytics	19.3.0
Crashlytics حزمة تطوير البرامج (NDK)	com.google.firebase:firebase-crashlytics-ndk	19.3.0
المكوّن الإضافي Crashlytics	com.google.firebase:firebase-crashlytics-gradle	3.0.2
إتاحة وحدات الميزات الديناميكية	com.google.firebase:firebase-dynamic-module-support	16.0.0-beta03
Dynamic Links	com.google.firebase:firebase-dynamic-links	22.1.0
In-App Messaging	com.google.firebase:firebase-inappmessaging	21.0.1	(مطلوبة)
In-App Messaging الشبكة الإعلانية	com.google.firebase:firebase-inappmessaging-display	21.0.1	(مطلوبة)
Firebase عملية تثبيت	com.google.firebase:firebase-installations	18.0.0
Firebase ML Model Downloader API	com.google.firebase:firebase-ml-modeldownloader	25.0.1
Performance Monitoring	com.google.firebase:firebase-perf	21.0.3
المكوّن الإضافي Performance Monitoring	com.google.firebase:perf-plugin	1.4.2
Realtime Database	com.google.firebase:firebase-database	21.0.0
Remote Config	com.google.firebase:firebase-config	22.0.1
Vertex AI in Firebase	com.google.firebase:firebase-vertexai	16.0.2
مكوّن إضافي لـ "خدمات Google Play"	com.google.gms:google-services	4.4.2
المكتبات المتوقّفة نهائيًا
App Check مقدّم خدمة SafetyNet	com.google.firebase:firebase-appcheck-safetynet	16.1.2
App Indexing	com.google.firebase:firebase-appindexing	20.0.0
وحدات Firebase KTX Analytics com.google.firebase:firebase-analytics-ktx 22.1.2 App Check مزوّد بيانات مخصّص com.google.firebase:firebase-appcheck-ktx 18.0.0 App Distribution API com.google.firebase:firebase-appdistribution-api-ktx 16.0.0-beta14 Authentication com.google.firebase:firebase-auth-ktx 23.1.0 Cloud Firestore com.google.firebase:firebase-firestore-ktx 25.1.1 Cloud Functions for Firebase Client SDK com.google.firebase:firebase-functions-ktx 21.1.0 Cloud Messaging com.google.firebase:firebase-messaging-ktx 24.1.0 Cloud Storage com.google.firebase:firebase-storage-ktx 21.0.1 Crashlytics com.google.firebase:firebase-crashlytics-ktx 19.3.0 Dynamic Links com.google.firebase:firebase-dynamic-links-ktx 22.1.0 In-App Messaging com.google.firebase:firebase-inappmessaging-ktx 21.0.1 (مطلوبة) In-App Messaging الشبكة الإعلانية com.google.firebase:firebase-inappmessaging-display-ktx 21.0.1 (مطلوبة) Firebase عملية تثبيت com.google.firebase:firebase-installations-ktx 18.0.0 Firebase ML Model Downloader API com.google.firebase:firebase-ml-modeldownloader-ktx 25.0.1 Performance Monitoring com.google.firebase:firebase-perf-ktx 21.0.3 Realtime Database com.google.firebase:firebase-database-ktx 21.0.0 Remote Config com.google.firebase:firebase-config-ktx 22.0.1
مكتبات Firebase ML Kit Firebase ML واجهات برمجة التطبيقات للنماذج المخصّصة com.google.firebase:firebase-ml-model-interpreter 22.0.4 Firebase ML واجهات برمجة تطبيقات Vision com.google.firebase:firebase-ml-vision 24.1.0 Firebase ML: نموذج تصنيف الصور com.google.firebase:firebase-ml-vision-image-label-model 20.0.2 Firebase ML: نموذج رصد الأجسام وتتبُّعها com.google.firebase:firebase-ml-vision-object-detection-model 19.0.6 Firebase ML: نموذج التعرّف على الوجوه com.google.firebase:firebase-ml-vision-face-model 20.0.2 Firebase ML: نموذج مسح الرمز الشريطي com.google.firebase:firebase-ml-vision-barcode-model 16.1.2 Firebase ML: AutoML Vision Edge API com.google.firebase:firebase-ml-vision-automl 18.0.6 Firebase ML: واجهات برمجة تطبيقات اللغة الطبيعية com.google.firebase:firebase-ml-natural-language 22.0.1 Firebase ML: نموذج تحديد اللغة com.google.firebase:firebase-ml-natural-language-language-id-model 20.0.8 Firebase ML: نموذج الترجمة com.google.firebase:firebase-ml-natural-language-translate-model 20.0.9 Firebase ML: نموذج الردّ السريع com.google.firebase:firebase-ml-natural-language-smart-reply-model 20.0.8

---

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

إضافة خدمات Firebase إلى تطبيقك:

• يمكنك الحصول على إحصاءات عن سلوك المستخدِم باستخدام Analytics.

• إعداد مسار مصادقة مستخدم باستخدام Authentication

• تخزين البيانات، مثل معلومات المستخدمين، باستخدام Cloud Firestore أو Realtime Database

• تخزين الملفات، مثل الصور والفيديوهات، باستخدام Cloud Storage

• يمكنك تنشيط رمز الخلفية الذي يتم تشغيله في بيئة آمنة باستخدام Cloud Functions.

• أرسِل إشعارات باستخدام Cloud Messaging.

• يمكنك معرفة حالات تعطُّل تطبيقك وسببها باستخدام Crashlytics.

مزيد من المعلومات عن Firebase:

• انتقِل إلى مقالة فهم مشاريع Firebase للاطّلاع على مزيد من المعلومات حول مشاريع Firebase وأفضل الممارسات المتعلّقة بها.

• انتقِل إلى مقالة مزيد من المعلومات عن Android وFirebase إذا كان لديك أسئلة عن المفاهيم غير المألوفة أو الخاصة بمنصّة Firebase وتطوير التطبيقات على Android.

• اطّلِع على عيّنات من تطبيقات Firebase.

• يمكنك الحصول على تجربة عملية من خلال Firebase Android Codelab.

• يمكنك الاطّلاع على مزيد من المعلومات من خلال الدورة التدريبية Firebase في عطلة نهاية الأسبوع.

• تجهيز تطبيقك للإطلاق:

  • إعداد تنبيهات الميزانية لمشروعك في وحدة تحكّم Google Cloud
  • يمكنك مراقبة لوحة بيانات الاستخدام والفوترة في وحدة تحكّم Firebase للحصول على نظرة عامة على استخدام مشروعك على مستوى خدمات Firebase المتعددة.
  • راجِع قائمة التحقّق من إطلاق Firebase.

• هل تواجه مشكلة في Firebase ومشروع Android؟ يُرجى الانتقال إلى تحديد المشاكل وحلّها في Android والأسئلة الشائعة.