فهم Firebase للويب

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

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

إصدارات حزمة تطوير البرامج (SDK): تتضمّن مساحة اسم ووحدة

يوفّر Firebase واجهتَي عرض لواجهة برمجة التطبيقات لتطبيقات الويب، وهما:

  • JavaScript: مساحة الاسم هذه هي واجهة JavaScript التي احتفظ بها Firebase لسنوات عديدة وهي مألوفة لمطوّري الويب الذين لديهم تطبيقات Firebase القديمة. نظرًا لأن واجهة برمجة التطبيقات التي تتضمن مساحة الاسم لا تستفيد من الدعم الجديد المستمر للميزات، يجب أن تستخدم معظم التطبيقات الجديدة واجهة برمجة التطبيقات modular API بدلاً من ذلك.
  • JavaScript - نمطي: وتستند حزمة تطوير البرامج (SDK) هذه إلى طريقة نموذجية توفّر حجمًا مصغرًا لحزمة SDK وكفاءة أكبر باستخدام أدوات إنشاء JavaScript الحديثة، مثل webpack أو Rollup.

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

على الرغم من أنّ معظم واجهات برمجة التطبيقات modular API تتبع الأنماط نفسها في واجهة برمجة التطبيقات التي تتضمّن مساحة الاسم، إلا أنّ تنظيم الرمز البرمجي مختلف. بشكل عام، تكون واجهة برمجة التطبيقات ذات مساحة الاسم موجهة نحو مساحة الاسم ونمط الخدمة، بينما تكون واجهة برمجة التطبيقات النمطية موجهة نحو الدوال المنفصلة. على سبيل المثال، يتم استبدال سلسلة النقاط الخاصة بواجهة برمجة التطبيقات التي تتضمّن مساحة الاسم، مثل firebaseApp.auth()، في واجهة برمجة التطبيقات النمطية بدالة getAuth() واحدة تأخذ firebaseApp وتعرض مثيل المصادقة.

وهذا يعني أن تطبيقات الويب التي تم إنشاؤها باستخدام واجهة برمجة التطبيقات ذات مساحة الاسم تتطلب إعادة البناء من أجل الاستفادة من تصميم التطبيق القائم على وحدات. اطّلِع على دليل الترقية لمزيد من التفاصيل.

JavaScript - واجهة برمجة تطبيقات نمطية للتطبيقات الجديدة

إذا كنت بصدد إجراء عملية دمج جديدة مع Firebase، يمكنك تفعيل واجهة برمجة التطبيقات النموذجية عند إضافة حزمة تطوير البرامج (SDK) وإعدادها.

أثناء تطوير التطبيق، يجب أن تضع في اعتبارك أنه سيتم تنظيم الرمز البرمجي بشكل أساسي حسب الدوال. في واجهة برمجة التطبيقات modular API، يتم تمرير الخدمات كوسيطة أولى، ثم تستخدم الدالة تفاصيل الخدمة لتنفيذ باقي المهام. على سبيل المثال:

import { getAuth, onAuthStateChanged } from "firebase/auth";

const auth = getAuth(firebaseApp);
onAuthStateChanged(auth, user => {
  // Check for user status
});

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

طرق إضافة حِزم تطوير البرامج (SDK) على الويب إلى تطبيقك

يوفّر Firebase مكتبات JavaScript لمعظم منتجات Firebase، بما في ذلك "الإعداد عن بُعد" و"المراسلة عبر السحابة الإلكترونية من Firebase" وغيرها. وتعتمد كيفية إضافة حِزم تطوير البرامج (SDK) لمنصة Firebase إلى تطبيق الويب على الأدوات التي تستخدمها مع تطبيقك (مثل أداة تجميع الوحدات).

يمكنك إضافة أيّ من المكتبات المتاحة إلى تطبيقك عبر إحدى الطرق المتوافقة:

  • npm (لبرامج حزم الوحدات)
  • CDN (شبكة توصيل المحتوى)

للحصول على تعليمات مفصّلة حول الإعداد، اطّلِع على مقالة إضافة Firebase إلى تطبيق JavaScript. ويحتوي باقي هذا القسم على معلومات لمساعدتك في الاختيار من بين الخيارات المتاحة.

دورة في الدقيقة

يوفّر لك تنزيل حزمة npm لمنصّة Firebase (التي تتضمّن حِزم المتصفّح وحِزم Node.js) نسخة محلية من حزمة تطوير البرامج (SDK) لمنصّة Firebase والتي قد تكون مطلوبة للتطبيقات التي لا تستخدم متصفّحًا مثل تطبيقات Node.js أو React Native أو Electron. تشتمل عملية التنزيل على حزمتَي Node.js وReact Native كخيار لبعض الحزم. تعتبر حزم Node.js ضرورية لخطوة العرض من جهة الخادم (SSR) في أطر عمل SSR.

إنّ استخدام npm مع برنامج لحزم الوحدات مثل webpack أو Rollup يوفّر خيارات تحسين تتيح تنفيذ رموز برمجية غير مستخدَمة على شكل شجرة وتطبيق رموز polyfill مستهدَفة، ما يمكن أن يؤدي إلى تقليل حجم التطبيق بشكل كبير. قد يؤدي تنفيذ هذه الميزات إلى إضافة بعض التعقيدات إلى عملية الضبط وسلسلة الإنشاء، إلا أنّ العديد من أدوات واجهة سطر الأوامر السائدة يمكن أن تساعد في الحدّ من هذا الأمر. وتشمل هذه الأدوات Angular وReact وVue والتالي وغيرها.

وباختصار:

  • تقديم تحسين قيّم لحجم التطبيق
  • تتوفّر أدوات فعّالة لإدارة الوحدات.
  • مطلوب لـ SSR مع Node.js

CDN (شبكة توصيل المحتوى)

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

وباختصار:

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

صيغ Firebase Web SDK

ويمكن استخدام حزمة تطوير البرامج (SDK) للويب من Firebase في كل من تطبيقات المتصفّحات وتطبيقات العقدة. ومع ذلك، لا تتوفّر العديد من المنتجات في بيئات العُقد. ويمكنك الاطّلاع على قائمة البيئات المتوافقة.

توفّر بعض حِزم تطوير البرامج (SDK) للمنتجات صيغًا منفصلة للمتصفّح وعقدة Node، ويتم توفير كل منهما بتنسيقَي ESM وCJS، بينما توفّر بعض حِزم SDK للمنتجات صيغًا من Cordova أو React Native. تم ضبط "حزمة تطوير البرامج (SDK) على الويب" لتوفير الصيغة الصحيحة استنادًا إلى بيئة الأدوات أو إعداداتها، ويجب ألا تتطلّب التحديد اليدوي في معظم الحالات. تم تصميم جميع إصدارات حزمة تطوير البرامج (SDK) للمساعدة في إنشاء تطبيقات الويب أو تطبيقات العميل لإتاحة وصول المستخدمين النهائيين، كما هو الحال في تطبيق Node.js لسطح المكتب أو تطبيقات إنترنت الأشياء (IoT). إذا كان هدفك هو إعداد إذن وصول إداري من البيئات المتميزة (مثل الخوادم)، استخدِم حزمة تطوير البرامج (SDK) لمشرف Firebase بدلاً من ذلك.

رصد البيئة باستخدام برامج التجميع وأُطر العمل

عند تثبيت حزمة تطوير البرامج (SDK) على الويب لمنصة Firebase باستخدام npm، يتم تثبيت إصدارَي JavaScript وNode.js. توفر الحزمة اكتشافًا تفصيليًا للبيئة لتمكين الحزم المناسبة لتطبيقك.

إذا كانت الرمز البرمجي يستخدم عبارات require في Node.js، ستعثر حزمة تطوير البرامج (SDK) على الحزمة الخاصة بالعُقدة. وبخلاف ذلك، يجب ضبط إعدادات أداة التجميع بشكل صحيح لرصد حقل نقطة الدخول الصحيح في ملف package.json (على سبيل المثال، main أو browser أو module). إذا حدثت أخطاء في وقت تشغيل حزمة تطوير البرامج (SDK)، تأكَّد من ضبط برنامج الحزمة لضمان تحديد نوع الحزمة الصحيح حسب الأولوية لبيئتك.

مزيد من المعلومات عن عنصر إعدادات Firebase

لإعداد Firebase في تطبيقك، عليك توفير إعدادات مشروع Firebase لتطبيقك. يمكنك الحصول على كائن إعداد Firebase في أي وقت.

  • لا ننصح بتعديل كائن الضبط يدويًا، لا سيما خيارات Firebase التالية المطلوبة: apiKey وprojectId وappID. في حال إعداد تطبيقك بقيم غير صالحة أو غير متوفّرة ضمن "خيارات Firebase" المطلوبة، قد يواجه مستخدمو تطبيقك مشاكل خطيرة. ويُستثنى من ذلك authDomain، إذ يمكن تعديله باتّباع أفضل الممارسات لاستخدام SignInWithRedirect.

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

  • في حال تفعيل "إحصاءات Google" أو "قاعدة بيانات الوقت الفعلي" بعد إنشاء تطبيق الويب على Firebase، تأكّد من تعديل عنصر ضبط Firebase الذي تستخدمه في تطبيقك باستخدام قيم الإعدادات المرتبطة به (measurementId وdatabaseURL، على التوالي). يمكنك الحصول على كائن إعداد Firebase في أي وقت.

وفي ما يلي تنسيق كائن config مع تفعيل جميع الخدمات (تتم تعبئة هذه القيم تلقائيًا):

var firebaseConfig = {
  apiKey: "API_KEY",
  authDomain: "PROJECT_ID.firebaseapp.com",
  // The value of `databaseURL` depends on the location of the database
  databaseURL: "https://DATABASE_NAME.firebaseio.com",
  projectId: "PROJECT_ID",
  storageBucket: "PROJECT_ID.appspot.com",
  messagingSenderId: "SENDER_ID",
  appId: "APP_ID",
  // For Firebase JavaScript SDK v7.20.0 and later, `measurementId` is an optional field
  measurementId: "G-MEASUREMENT_ID",
};

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

خيارات الإعداد الإضافية

تأخير تحميل حِزم تطوير البرامج (SDK) لمنصة Firebase (من شبكة توصيل المحتوى)

يمكنك تأخير تضمين حِزم تطوير البرامج (SDK) لمنصّة Firebase إلى أن يتم تحميل الصفحة بأكملها. إذا كنت تستخدم نصوصًا برمجية نموذجية لواجهة برمجة التطبيقات CDN مع <script type="module">، هذا هو السلوك التلقائي. إذا كنت تستخدم النصوص البرمجية لشبكة توصيل المحتوى (CDN) ذات مساحة الاسم كوحدة، أكمِل هذه الخطوات لتأجيل التحميل:

  1. أضِف علامة defer إلى كل علامة script لحِزم تطوير البرامج (SDK) لمنصة Firebase، ثم أجِّل إعداد Firebase باستخدام نص برمجي ثانٍ، على سبيل المثال:

    <script defer src="https://www.gstatic.com/firebasejs/8.10.1/firebase-app.js"></script>

<script defer src="https://www.gstatic.com/firebasejs/8.10.1/firebase-auth.js"></script>
<script defer src="https://www.gstatic.com/firebasejs/8.10.1/firebase-firestore.js"></script>

// ...

<script defer src="./init-firebase.js"></script>

  2. أنشئ ملف init-firebase.js، ثم ضمِّن ما يلي في الملف:

    // TODO: Replace the following with your app's Firebase project configuration
var firebaseConfig = {
  // ...
};

// Initialize Firebase
firebase.initializeApp(firebaseConfig);

استخدام عدّة مشاريع في Firebase في تطبيق واحد

في معظم الحالات، سيكون عليك إعداد Firebase في تطبيق تلقائي واحد فقط. ويمكنك الوصول إلى Firebase من هذا التطبيق بطريقتَين مكافئتَين:

واجهة برمجة التطبيقات Web modular API

import { initializeApp } from "firebase/app";
import { getStorage } from "firebase/storage";
import { getFirestore } from "firebase/firestore";

// Initialize Firebase with a "default" Firebase project
const defaultProject = initializeApp(firebaseConfig);

console.log(defaultProject.name);  // "[DEFAULT]"

// Option 1: Access Firebase services via the defaultProject variable
let defaultStorage = getStorage(defaultProject);
let defaultFirestore = getFirestore(defaultProject);

// Option 2: Access Firebase services using shorthand notation
defaultStorage = getStorage();
defaultFirestore = getFirestore();
app_default_init_options.js

واجهة برمجة التطبيقات لمساحة الاسم على الويب

// Initialize Firebase with a "default" Firebase project
const defaultProject = firebase.initializeApp(firebaseConfig);

console.log(defaultProject.name);  // "[DEFAULT]"

// Option 1: Access Firebase services via the defaultProject variable
let defaultStorage = defaultProject.storage();
let defaultFirestore = defaultProject.firestore();

// Option 2: Access Firebase services using shorthand notation
defaultStorage = firebase.storage();
defaultFirestore = firebase.firestore();
firebaseapp.js

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

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

واجهة برمجة التطبيقات Web modular API

import { initializeApp, getApp } from "firebase/app";
import { getStorage } from "firebase/storage";
import { getFirestore } from "firebase/firestore";

// Initialize Firebase with a default Firebase project
initializeApp(firebaseConfig);

// Initialize Firebase with a second Firebase project
const otherProject = initializeApp(otherProjectFirebaseConfig, "other");

console.log(getApp().name);  // "[DEFAULT]"
console.log(otherProject.name);    // "otherProject"

// Use the shorthand notation to access the default project's Firebase services
const defaultStorage = getStorage();
const defaultFirestore = getFirestore();

// Use the otherProject variable to access the second project's Firebase services
const otherStorage = getStorage(otherProject);
const otherFirestore = getFirestore(otherProject);
app_multi_project_init_options.js

واجهة برمجة التطبيقات لمساحة الاسم على الويب

// Initialize Firebase with a default Firebase project
firebase.initializeApp(firebaseConfig);

// Initialize Firebase with a second Firebase project
const otherProject = firebase.initializeApp(otherProjectFirebaseConfig, "other");

console.log(firebase.app().name);  // "[DEFAULT]"
console.log(otherProject.name);    // "otherProject"

// Use the shorthand notation to access the default project's Firebase services
const defaultStorage = firebase.storage();
const defaultFirestore = firebase.firestore();

// Use the otherProject variable to access the second project's Firebase services
const otherStorage = otherProject.storage();
const otherFirestore = otherProject.firestore();
firebaseapp.js

تشغيل خادم ويب محلي للتطوير

إذا كنت تنشئ تطبيق ويب، تتطلب بعض أجزاء من حزمة تطوير البرامج (SDK) لـ Firebase JavaScript عرض تطبيق الويب من خادم بدلاً من نظام الملفات على الجهاز. يمكنك استخدام واجهة سطر الأوامر في Firebase لتشغيل خادم محلي.

إذا سبق لك إعداد استضافة Firebase لتطبيقك، قد تكون سبق لك إكمال العديد من الخطوات الواردة أدناه.

لعرض تطبيق الويب، يجب استخدام واجهة سطر الأوامر في Firebase، وهي أداة سطر أوامر.

  1. يمكنك الانتقال إلى مستندات واجهة سطر الأوامر في Firebase للتعرّف على كيفية تثبيت واجهة سطر الأوامر أو التحديث إلى أحدث إصدار منه.

  2. إعداد مشروع Firebase: شغِّل الأمر التالي من جذر دليل التطبيق المحلي:

    firebase init

  3. ابدأ تشغيل الخادم المحلي من أجل التطوير. شغِّل الأمر التالي من جذر دليل التطبيق المحلي:

    firebase serve

مراجع مفتوحة المصدر لحِزم تطوير البرامج (SDK) الخاصة بلغة JavaScript لمنصّة Firebase

يدعم Firebase تطوير البرامج مفتوحة المصدر، ونحن نشجع مساهمات المنتدى والملاحظات.

حِزم تطوير البرامج (SDK) لمنصّة Firebase الخاصة بلغة JavaScript

تم تطوير معظم حِزم SDK لـ Firebase JavaScript كمكتبات مفتوحة المصدر في مستودع Firebase GitHub العام.

نماذج البدء السريع

يحتفظ Firebase بمجموعة من نماذج البدء السريع لمعظم واجهات برمجة تطبيقات Firebase على الويب. يمكنك الاطّلاع على لحظات الانطلاق السريعة هذه في مستودع GitHub GitHub العام المتاح للجميع. ويمكنك استخدام نقاط البداية السريعة هذه كمثال على الرمز لاستخدام حِزم تطوير البرامج (SDK) لمنصّة Firebase.