استخدام Firebase في تطبيقات الويب الديناميكية باستخدام ميزة "العرض من جهة الخادم"

إذا كنت قد عملت من قبل على Firebase JS SDK أو حِزم Firebase SDK الأخرى من جهة العميل، من المحتمل أنّك على دراية بواجهة FirebaseApp وكيفية استخدامها لإعداد مثيلات التطبيقات. لتسهيل العمليات المماثلة على جهة الخادم، توفّر Firebase واجهة FirebaseServerApp.

FirebaseServerApp هي صيغة مختلفة من FirebaseApp تُستخدم في بيئات العرض من جهة الخادم (SSR). وتتضمّن أدوات لمواصلة جلسات Firebase التي تمتدّ على نطاق العرض من جهة العميل (CSR) والعرض من جهة الخادم. يمكن أن تساعد هذه الأدوات والاستراتيجيات في تحسين تطبيقات الويب الديناميكية التي تم إنشاؤها باستخدام Firebase و تم نشرها في بيئات Google، مثل Firebase App Hosting.

استخدِم FirebaseServerApp من أجل:

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

مراحل النشاط في FirebaseServerApp

تعمل أُطر العرض من جهة الخادم (SSR) وأوقات التشغيل الأخرى غير المتصفّح، مثل عاملي السحابة الإلكترونية، على تحسين وقت الإعداد من خلال إعادة استخدام الموارد في عمليات التنفيذ المتعدّدة. تم تصميم FirebaseServerApp لاستيعاب هذه البيئات من خلال استخدام آلية عدد المَراجع. إذا استدعى أحد التطبيقات initializeServerApp بالمعلّمات نفسها التي تم استخدامها في initializeServerApp سابقًا، سيتلقّى مثيل FirebaseServerApp نفسه الذي تم إعداده من قبل. يقلّل ذلك من النفقات غير الضرورية للإعداد وتخصيص الذاكرة. عند استدعاء deleteApp على مثيل FirebaseServerApp، يتم خفض عدد المَراجع، ويتم تحرير المثيل بعد أن يصل عدد المَراجع إلى صفر.

تنظيف مثيلات FirebaseServerApp

قد يكون من الصعب معرفة الوقت المناسب لاستدعاء deleteApp على مثيل FirebaseServerApp، خاصةً إذا كنت تُشغّل العديد من العمليات غير المتزامنة بالتوازي. يساعد الحقل releaseOnDeref في FirebaseServerAppSettings على تبسيط هذه العملية. إذا خصّصت لـ releaseOnDeref مرجعًا إلى عنصر له فترة بقاء نطاق الطلب (على سبيل المثال، عنصر العناوين لطلب العرض من جهة الخادم)، سيقلّل FirebaseServerApp عدد المَراجع عندما يستردّ الإطار عنصر العنوان. يؤدي ذلك إلى تنظيف مثيل FirebaseServerApp تلقائيًا.

في ما يلي مثال على استخدام releaseOnDeref:

/// Next.js
import { headers } from 'next/headers'
import { FirebaseServerAppSettings, initializeServerApp} from "firebase/app";

export default async function Page() {
  const headersObj = await headers();
  let appSettings: FirebaseServerAppSettings = {};
  appSettings.releaseOnDeref = headersObj;
  const serverApp = initializeServerApp(firebaseConfig, appSettings);
  ...
}

استئناف الجلسات التي تم إنشاؤها من جهة العميل والمصادقة عليها

عند إعداد مثيل من FirebaseServerApp باستخدام رمز مميز لتعريف المصادقة، يتيح ذلك ربط جلسات المستخدمين الذين تمّت المصادقة عليهم بين بيئات العرض من جهة العميل (CSR) والعرض من جهة الخادم (SSR). ستحاول مثيلات Firebase Auth SDK التي تم إعدادها باستخدام عنصر FirebaseServerApp يحتوي على رمز تعريف المصادقة تسجيل دخول المستخدم عند الإعداد بدون الحاجة إلى أن يستدعي التطبيق أيًا من طرق تسجيل الدخول.

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

/// Next.js
import { initializeServerApp } from "firebase/app";
import { getAuth } from "firebase/auth";

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

const firebaseServerAppSettings = {
  authIdToken: token  // See "Pass client tokens to the server side
                      // rendering phase" for an example on how transmit
                      // the token from the client and the server.
}

const serverApp =
  initializeServerApp(firebaseConfig,
                      firebaseServerAppSettings);
const serverAuth = getAuth(serverApp);

// FirebaseServerApp and Auth will now attempt
// to sign in the current user based on provided
// authIdToken.

استخدام ميزة "فحص التطبيقات" في بيئات العرض من جهة الخادم

تعتمد عملية فرض ميزة "فحص التطبيقات" على مثيل من App Check SDK تستخدمه حِزم Firebase SDK لاستدعاء getToken داخليًا. يتم بعد ذلك تضمين الرمز الناتج في الطلبات المقدّمة إلى جميع خدمات Firebase، ما يسمح للخادم الخلفي بالتحقّق من التطبيق.

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

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

/// Next.js
import { initializeServerApp } from "firebase/app";

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

const firebaseServerAppSettings = {
  appCheckToken: token // See "Pass client tokens to the server side
                       // rendering phase" for an example on how transmit
                       // the token from the client and the server.
}

const serverApp =
  initializeServerApp(firebaseConfig,
                      firebaseServerAppSettings);

// The App Check token will now be appended to all Firebase service requests.

تمرير رموز تعريف العميل إلى مرحلة العرض من جهة الخادم

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

راجِع إدارة الجلسات باستخدام عاملي الخدمة للحصول على نموذج لتنفيذ عامل خدمة Firebase Auth. اطّلِع أيضًا على التغييرات من جهة الخادم للاطّلاع على رمز يوضّح كيفية تحليل هذه الرموز من العناوين لاستخدامها في FirebaseServerApp إعداد.

استخدام Firestore في بيئات العرض من جهة الخادم

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

يوضّح هذا القسم كيفية إعادة استخدام البيانات التي تم استردادها أثناء مرحلة العرض من جهة الخادم ضمن المكوّنات من جهة العميل.

تسلسل أنواع البيانات

توفّر بعض أنواع بيانات Firestore طريقة toJSON لتحويل بياناتها إلى تنسيق قابل للتسلسل. ويشمل ذلك مثيلات الكائنات، مثل Bytes وGeoPoint وTimestamp وVectorValue.

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

import {
  Bytes
} from 'firebase/firestore';

const BYTES_DATA = new Uint8Array([0, 1, 2, 3, 4, 5]);
const bytes = Bytes.fromUint8Array(BYTES_DATA);
const bytesJSON = bytes.toJSON();

إلغاء تسلسل أنواع البيانات

تتضمّن أنواع بيانات Firestore الطريقة الثابتة fromJSON لتحويل البيانات المتسلسلة إلى نوع بيانات Firestore قابل للتشغيل.

على سبيل المثال، يؤدي ما يلي إلى إلغاء تسلسل نوع بيانات Bytes:

import {
  Bytes
} from 'firebase/firestore';

// Assuming the same `bytesJSON` variable from the previous example.
const deserializedBytes = Bytes.fromJSON(bytesJSON);

تسلسل وإلغاء تسلسل لقطات Firestore

على غرار أنواع بيانات Firestore، يمكنك تسلسل مثيلات DocumentSnapshot وQuerySnapshot باستخدام toJSON. ومع ذلك، لإلغاء تسلسلها، يجب استخدام الدالتَين المستقلتَين documentSnapshotFromJSON وquerySnapshotFromJSON بدلاً من الطريقة الثابتة fromJSON.

على سبيل المثال، يمكن تسلسل نتائج querySnapshot لعملية query باستخدام طريقة toJSON

import {
  collection,
  getDocs,
  query,
  querySnapshotFromJSON
} from 'firebase/firestore';
// Assuming a configured instance of Firestore in the variable `firestore`.
const queryRef = query(collection(firestore, QUERY_PATH));
const querySnapshot = await getDocs(queryRef);
const querySnapshotJson = querySnapshot.toJSON();

بعد ذلك، يمكن إلغاء تسلسل هذه البيانات:

import {
  querySnapshotFromJSON
} from 'firebase/firestore';

// deserializedSnapshot is an object of type QuerySnapshot:

const deserializedSnapshot =
  querySnapshotFromJSON(firestore, querySnapshotJson);

المستمعون الذين لديهم لقطات متسلسلة

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

إذا كان تطبيقك يتطلّب هذه آخر الأخبار في الوقت الفعلي، يمكنك استخدام الدالة onSnapshotResume لإعداد Firestore SnapshotListenerباستخدام بيانات Snapshot المتسلسلة. على سبيل المثال:

const observer = {
  next: (qs) => {
    console.log("onSnapshot invoked: ", qs.data());
  },
  error: (e) => {
    console.log("error callback invoked: ", e.toString());
  }
};
const unsubscribe = onSnapshotResume(firestore, querySnapshotJson, observer);