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

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

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

استخدِم FirebaseServerApp لتنفيذ ما يلي:

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

دورة حياة FirebaseServerApp

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

جارٍ حذف مثيلات FirebaseServerApp

قد يكون من الصعب معرفة متى يجب استدعاء deleteApp في مثيل FirebaseServerApp، خاصةً إذا كنت تُجري العديد من العمليات غير المتزامنة بشكل متوازٍ. يساعد حقل releaseOnDeref في FirebaseServerAppSettings في تبسيط ذلك. إذا عيّنت releaseOnDeref مرجعًا لكائن له عمر نطاق الطلب (على سبيل المثال، كائن الرؤوس لطلب SSR)، سيقلل 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). ستحاول مثيلات حزمة تطوير البرامج (SDK) لخدمة Firebase Auth التي تم إعدادها باستخدام عنصر FirebaseServerApp يحتوي على رمز مميّز لتعريف المصادقة تسجيل دخول المستخدم عند الإعداد بدون الحاجة إلى أن يستدعي التطبيق أي طرق لتسجيل الدخول.

يتيح توفير رمز مميّز لتعريف المصادقة للتطبيقات استخدام أي من طرق تسجيل الدخول الخاصة بالمصادقة على العميل، ما يضمن استمرار الجلسة من جهة الخادم، حتى بالنسبة إلى طرق تسجيل الدخول التي تتطلب تفاعل المستخدم. بالإضافة إلى ذلك، تتيح هذه الميزة إمكانية نقل العمليات المكثّفة إلى الخادم، مثل طلبات البحث المصادق عليها في 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.

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

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

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

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

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

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

توفّر بعض أنواع بيانات 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);

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

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

إذا كان تطبيقك يتطلّب هذه التعديلات في الوقت الفعلي، يمكنك استخدام الدالة onSnapshotResume لإعداد SnapshotListeners في Firestore باستخدام بيانات 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);