إضافة 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 A/B Testing وCloud Messaging وCrashlytics وIn-App Messaging وRemote Config (بما في ذلك التخصيص).

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

5. انقر على إنشاء مشروع (أو إضافة Firebase، إذا كنت تضيف 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).

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

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

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

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

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

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

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

1. نزِّل ملف إعداد Firebase الخاص بتطبيقك (google-services.json) ثم أضِفه إلى قاعدة الرموز البرمجية:

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

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

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

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

   • يمكنك تنزيل ملف إعدادات Firebase مرة أخرى في أي وقت.

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

2. لإتاحة الوصول إلى القيم في ملف الإعداد google-services.json لحِزم تطوير البرامج (SDK) في Firebase، يجب استخدام مكوّن Gradle الإضافي لخدمات Google (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.3" 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.3' 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:34.0.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.

   لم يتم تفعيل Analytics

   dependencies {
     // ...
   
     // Import the Firebase BoM
     implementation(platform("com.google.firebase:firebase-bom:34.0.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.

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

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

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

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

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

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

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

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

---

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

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

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

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

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

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

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

      ما هي الإجراءات التي ينفّذها سير العمل هذا؟

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

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

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

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

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

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

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

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

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

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

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

---

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

يسرد هذا القسم منتجات Firebase المتوافقة مع Android وتبعيات Gradle الخاصة بها. مزيد من المعلومات عن مكتبات Firebase Android هذه:

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

• ‫Firebase Android SDK مستودع 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 هذا.	34.0.0
AdMob	com.google.android.gms:play-services-ads	24.4.0
Firebase AI Logic 1	com.google.firebase:firebase-ai	‫17.0.0
Analytics	com.google.firebase:firebase-analytics	23.0.0
App Check مزوّد مخصّص	com.google.firebase:firebase-appcheck	‫19.0.0
App Check موفّر تصحيح الأخطاء	com.google.firebase:firebase-appcheck-debug	‫19.0.0
App Check مقدّم خدمة Play Integrity	com.google.firebase:firebase-appcheck-playintegrity	‫19.0.0
App Distribution	com.google.firebase:firebase-appdistribution	‫16.0.0-beta16
App Distribution API	com.google.firebase:firebase-appdistribution-api	‫16.0.0-beta16
App Distribution المكوّن الإضافي	com.google.firebase:firebase-appdistribution-gradle	5.1.1
Authentication	com.google.firebase:firebase-auth	24.0.0
Cloud Firestore	com.google.firebase:firebase-firestore	‫26.0.0
Cloud Functions for Firebase Client SDK	com.google.firebase:firebase-functions	22.0.0
Cloud Messaging	com.google.firebase:firebase-messaging	25.0.0
Cloud Storage	com.google.firebase:firebase-storage	22.0.0
Crashlytics	com.google.firebase:firebase-crashlytics	20.0.0
Crashlytics NDK	com.google.firebase:firebase-crashlytics-ndk	20.0.0
Crashlytics المكوّن الإضافي	com.google.firebase:firebase-crashlytics-gradle	3.0.5
Data Connect	com.google.firebase:firebase-dataconnect	‫17.0.0
إتاحة استخدام وحدات الميزات الديناميكية	com.google.firebase:firebase-dynamic-module-support	16.0.0-beta04
Dynamic Links	com.google.firebase:firebase-dynamic-links	‫22.1.0
In-App Messaging	com.google.firebase:firebase-inappmessaging	22.0.0	(مطلوب)
In-App Messaging الشبكة الإعلانية	com.google.firebase:firebase-inappmessaging-display	22.0.0	(مطلوب)
Firebase من عمليات التثبيت	com.google.firebase:firebase-installations	‫19.0.0
Firebase ML واجهة برمجة التطبيقات Model Downloader API	com.google.firebase:firebase-ml-modeldownloader	‫26.0.0
Performance Monitoring	com.google.firebase:firebase-perf	22.0.0
Performance Monitoring المكوّن الإضافي	com.google.firebase:perf-plugin	2.0.0
Realtime Database	com.google.firebase:firebase-database	22.0.0
Remote Config	com.google.firebase:firebase-config	23.0.0
مكوّن "خدمات Google Play" الإضافي	com.google.gms:google-services	4.4.3
المكتبات المتوقّفة نهائيًا
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.5.0 App Check مزوّد مخصّص com.google.firebase:firebase-appcheck-ktx 18.0.0 App Distribution API com.google.firebase:firebase-appdistribution-api-ktx ‫16.0.0-beta15 Authentication com.google.firebase:firebase-auth-ktx 23.2.1 Cloud Firestore com.google.firebase:firebase-firestore-ktx ‫25.1.4 Cloud Functions for Firebase Client SDK com.google.firebase:firebase-functions-ktx ‫21.2.1 Cloud Messaging com.google.firebase:firebase-messaging-ktx ‫24.1.2 Cloud Storage com.google.firebase:firebase-storage-ktx ‫21.0.2 Crashlytics com.google.firebase:firebase-crashlytics-ktx ‫19.4.4 Dynamic Links com.google.firebase:firebase-dynamic-links-ktx ‫22.1.0 In-App Messaging com.google.firebase:firebase-inappmessaging-ktx ‫21.0.2 (مطلوب) In-App Messaging الشبكة الإعلانية com.google.firebase:firebase-inappmessaging-display-ktx ‫21.0.2 (مطلوب) 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.5 Realtime Database com.google.firebase:firebase-database-ktx 21.0.0 Remote Config com.google.firebase:firebase-config-ktx 22.1.2
مكتبات Firebase ML Kit Firebase ML واجهات برمجة التطبيقات الخاصة بالنماذج المخصّصة com.google.firebase:firebase-ml-model-interpreter ‫22.0.4 Firebase ML واجهات Vision API 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 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

^{1 كان اسم Firebase AI Logic سابقًا "Vertex AI in Firebase" مع الحزمة com.google.firebase:firebase-vertexai.}

---

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

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

• إنشاء ميزات مستندة إلى الذكاء الاصطناعي التوليدي باستخدام نماذج Gemini وImagen باستخدام Firebase AI Logic

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

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

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

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

• تفعيل رمز الخلفية الذي يتم تنفيذه في بيئة آمنة باستخدام Cloud Functions

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

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

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

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

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

• استكشاف تطبيقات Firebase نموذجية

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

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

• استعِدّ لإطلاق تطبيقك باتّباع الخطوات التالية:

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

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