فهم Firebase للويب

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

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

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

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

  • JavaScript - namespaced. هذه هي واجهة JavaScript التي حافظت عليها Firebase لسنوات عديدة، وهي مألوفة لمطوّري الويب الذين يستخدمون تطبيقات Firebase القديمة. بما أنّ واجهة برمجة التطبيقات ذات مساحة الاسم لا تستفيد من إتاحة الميزات الجديدة بشكل مستمر، يجب أن تستخدم معظم التطبيقات الجديدة واجهة برمجة التطبيقات النموذجية بدلاً من ذلك.
  • JavaScript - معياري. تستند حزمة 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 وغير ذلك. تعتمد كيفية إضافة Firebase SDKs إلى تطبيق الويب الخاص بك على الأدوات التي تستخدمها مع تطبيقك (مثل حزمة الوحدات النمطية).

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

  • 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. راجع قائمة البيئات المدعومة.

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

اكتشاف البيئة باستخدام الحزم والأطر

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

إذا كان الكود الخاص بك يستخدم عبارات Node.js require، فستجد مجموعة أدوات التطوير البرمجية (SDK) الحزمة الخاصة بـ Node.js. بخلاف ذلك، يجب ضبط إعدادات أداة الحزم لديك بشكل صحيح لاكتشاف حقل نقطة الإدخال الصحيح في ملف 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 Web App الخاص بك، فتأكد من تحديث كائن تكوين 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 (من شبكة توصيل المحتوى)

بإمكانك تأخير تضمين SDKs Firebase حتى يتم تحميل الصفحة بالكامل. إذا كنت تستخدم نصوص CDN API المعيارية مع <script type="module">، فهذا هو السلوك الافتراضي. إذا كنت تستخدم نصوص CDN المخصصة كوحدة نمطية، فاتبع الخطوات التالية لتأجيل التحميل:

  1. أضف علامة defer إلى كل علامة script لمجموعات Firebase SDK، ثم قم بتأجيل تهيئة 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 CLI للتعرّف على كيفية تثبيت CLI أو التحديث إلى الإصدار الأخير.

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

    firebase init

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

    firebase serve

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

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

حِزم Firebase JavaScript SDK

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

نماذج Quickstart

تحتفظ Firebase بمجموعة من عينات البدء السريع لمعظم واجهات برمجة تطبيقات Firebase على الويب. يمكنك العثور على هذه البدائل السريعة في مستودع البدائل السريعة لـ Firebase GitHub العام الخاص بنا. يمكنك استخدام هذه البدايات السريعة كمثال على الكود لاستخدام Firebase SDKs.