فهم Firebase للويب

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

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

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

توفّر منصة Firebase مساحات عرض في واجهة برمجة التطبيقات لتطبيقات الويب:

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

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

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

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

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

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

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

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

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

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

وباختصار:

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

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

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

وباختصار:

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

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

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

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

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

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

إذا كان الرمز البرمجي يستخدم عبارات Node.js require، تعثر حزمة 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 في أي وقت.

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

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 (من شبكة توصيل المحتوى (CDN))

يمكنك تأخير تضمين حِزم تطوير البرامج (SDK) لمنصّة Firebase إلى أن يتم تحميل الصفحة بأكملها. إذا كنت تستخدم النصوص البرمجية النموذجية لواجهة برمجة التطبيقات في شبكة توصيل المحتوى مع <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 من هذا التطبيق بطريقتَين متكافئتَين:

واجهة برمجة تطبيقات الويب النموذجية

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();

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

// 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();

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

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

واجهة برمجة تطبيقات الويب النموذجية

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);

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

// 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();

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

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

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

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

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

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

    firebase init

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

    firebase serve

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

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

حِزم تطوير البرامج (SDK) المستندة إلى JavaScript لمنصة Firebase

تم تطوير معظم حِزم تطوير البرامج (SDK) المستندة إلى JavaScript لمنصة Firebase كمكتبات مفتوحة المصدر في مستودع Firebase GitHub العام.

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

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