فهم Firebase للويب

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

توفّر Firebase مكتبات JavaScript لمعظم منتجات Firebase، بما في ذلك Remote Config وFCM وغير ذلك. تعتمد طريقة إضافة حِزم تطوير البرامج (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 أو Rollup، خيارات تحسين "إزالة الأجزاء غير المستخدَمة من الرمز البرمجي" وتطبيق عمليات التعبئة المتوافقة المستهدَفة، ما يمكن أن يقلّل بشكل كبير من حجم تطبيقك. وقد يؤدي تنفيذ هذه الميزات إلى زيادة بعض التعقيد في عملية الإعداد وسلسلة الإنشاء، ولكن يمكن أن تساعد العديد من أدوات سطر الأوامر الشائعة في التخفيف من ذلك، مثل Angular وReact وVue وNext وغيرها.

وباختصار:

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

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

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

وباختصار:

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

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

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

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

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

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

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

التعرّف على عنصر إعدادات Firebase

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

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

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

  • في حال تفعيل Google Analytics أو Realtime Database بعد إنشاء تطبيق الويب على 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",
  // The value of `storageBucket` depends on when you provisioned your default bucket (learn more)
  storageBucket: "PROJECT_ID.firebasestorage.app",
  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 configuration
var firebaseConfig = {
  // ...
};

// Initialize Firebase
firebase.initializeApp(firebaseConfig);

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

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

Web

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

Web

// 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) Firebase JavaScript تهيئة واستخدام مشاريع متعددة على Firebase في تطبيق واحد في الوقت نفسه، مع استخدام كل مشروع لمعلومات إعدادات Firebase الخاصة به.

Web

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

Web

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

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

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

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

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

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

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

    firebase init

  3. ابدأ الخادم المحلي للتطوير. نفِّذ الأمر التالي من جذر دليل التطبيق على جهازك:

    firebase serve

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

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

حِزم Firebase JavaScript SDK

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

نماذج Quickstart

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