فهم Firebase للويب

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

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

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

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

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

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

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

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

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 على الحقل 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();
app_default_init_options.js

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();
firebaseapp.js

ومع ذلك، تحتاج أحيانًا إلى الوصول إلى مشاريع متعددة على 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);
app_multi_project_init_options.js

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();
firebaseapp.js

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

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

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

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

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

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

    firebase init

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

    firebase serve

مراجع مفتوحة المصدر لحِزم Firebase JavaScript SDK

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

حِزم Firebase JavaScript SDK

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

أمثلة على Quickstart

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