מוסיפים בקלות כניסה לאפליקציית האינטרנט באמצעות FirebaseUI

‫FirebaseUI for Web היא קבוצה של ספריות שמבוססות על אימות ב-Firebase JavaScript SDK, ועוזרות לכם להשיק במהירות תהליכי אימות.

‫FirebaseUI for Web מספק את היתרונות הבאים:

  • תמיכה ב-SDK מודולרי מודרני עם initializeApp(...) ו-Firebase JS SDK הנוכחי.
  • מסכים, טפסים ולחצנים שאפשר להרכיב מהם ממשק משתמש במקום ווידג'ט מונוליטי יחיד.
  • תמיכה ב-React,‏ Shadcn ו-Angular.
  • התנהגויות שניתנות להגדרה להפניה אוטומטית לעומת חלונות קופצים, Google One Tap, שדרוג אנונימי, הגדרות טלפון ועוד.
  • תמיכה בלוקליזציה דרך @firebase-oss/ui-translations.
  • תמיכה מובנית באימות באמצעות אימייל/סיסמה, קישור לאימייל, אימות טלפוני, ספקי OAuth ותהליכי אימות רב-שלבי.

במדריך הזה מוסבר איך להתקין, להפעיל, להיכנס ולהגדיר אפליקציות React,‏ Shadcn ו-Angular.

לפני שמתחילים

  1. מוסיפים את Firebase לאפליקציית האינטרנט:

    מפעילים את האימות במסוף Firebase.

    אם firebase עדיין לא מותקן בפרויקט, מתקינים אותו:

    npm install firebase

    שימוש ב-Firebase JS SDK מודולרי:

    import { initializeApp } from 'firebase/app';

const app = initializeApp({
  /* your Firebase config */
});

  2. בוחרים את הפלטפורמה ומתקינים את FirebaseUI:

    באפליקציות React שמבוססות על shadcn/ui, מוסיפים את מאגר Firebase ל-components.json:

    {
  "registries": {
    "@firebase": "https://firebaseopensource.com/r/{name}.json"
  }
}

    רכיבי האימות שבהם נעשה שימוש במדריך הזה זמינים במאגר הזה, כולל sign-in-auth-screen, sign-up-auth-screen, email-link-auth-screen, oauth-screen, phone-auth-screen, google-sign-in-button, apple-sign-in-button ו-github-sign-in-button.

    לאחר מכן מוסיפים את הרכיבים שרוצים להשתמש בהם:

    npx shadcn@latest add @firebase/sign-in-auth-screen @firebase/google-sign-in-button

    הפעולה הזו מתקינה את יחסי התלות הבסיסיים של React FirebaseUI.

    באפליקציות React בלי shadcn/ui, מתקינים את:

    npm install @firebase-oss/ui-react@beta @firebase-oss/ui-styles

    באפליקציות Angular, מתקינים את:

    npm install @angular/fire @firebase-oss/ui-angular@beta @firebase-oss/ui-core@beta @firebase-oss/ui-styles@beta

מפעילים את FirebaseUI

יוצרים מאגר משותף של ממשק משתמש באמצעות initializeUI(...), ואז מעבירים אותו לשילוב של המסגרת.

React

import { initializeApp } from 'firebase/app';
import { initializeUI } from '@firebase-oss/ui-core';
import { FirebaseUIProvider } from '@firebase-oss/ui-react';

const app = initializeApp({
  /* your Firebase config */
});

const ui = initializeUI({
  app,
});

export function AppProviders({ children }: { children: React.ReactNode }) {
  return <FirebaseUIProvider ui={ui}>{children}</FirebaseUIProvider>;
}

Shadcn

‫Shadcn משתמש באותה הגדרה כמו React, כי הוא גם משתמש ב-@firebase-oss/ui-react מתחת לפני השטח:

import { initializeApp } from 'firebase/app';
import { initializeUI } from '@firebase-oss/ui-core';
import { FirebaseUIProvider } from '@firebase-oss/ui-react';

const app = initializeApp({
  /* your Firebase config */
});

const ui = initializeUI({
  app,
});

export function AppProviders({ children }: { children: React.ReactNode }) {
  return <FirebaseUIProvider ui={ui}>{children}</FirebaseUIProvider>;
}

הרכיבים האלה משתמשים בסגנונות הקיימים של shadcn, ובדרך כלל לא מייבאים את ה-CSS שכלול ב-FirebaseUI כשמשתמשים במאגר של shadcn.

Angular

import { type ApplicationConfig } from '@angular/core';
import { provideFirebaseApp, initializeApp } from '@angular/fire/app';
import { provideFirebaseUI } from '@firebase-oss/ui-angular';
import { initializeUI } from '@firebase-oss/ui-core';

export const appConfig: ApplicationConfig = {
  providers: [
    provideFirebaseApp(() =>
      initializeApp({
        /* your Firebase config */
      }),
    ),
    provideFirebaseUI((apps) =>
      initializeUI({
        app: apps[0],
      }),
    ),
  ],
};

הכללת סגנונות

ב-FirebaseUI יש רכיבי ממשק משתמש מוכנים מראש ל-React ול-Angular. כדי להשתמש ברכיבים, צריך לכלול את ה-CSS שלהם:

אם אתם משתמשים ב-Tailwind עם React או Angular:

אחרת, צריך לכלול את הסגנונות של FirebaseUI:

@import '@firebase-oss/ui-styles/dist.min.css';

‫FirebaseUI לאתרים תומך בשינוי של ערכי ברירת המחדל של משתני CSS כדי להתאים אישית את העיצוב. פרטים נוספים זמינים במסמכי התיעוד בנושא עיצוב.

הגדרת שיטות כניסה לחשבון

כדי שהמשתמשים יוכלו להיכנס, צריך להפעיל כל ספק שרוצים להשתמש בו בקטע אימות -> שיטת כניסה במסוף Firebase.

‫FirebaseUI for Web משתמש במסכים, בטפסים ובלחצנים שמוצגים ישירות. ההגדרה המשותפת של התהליכים האלה נמצאת ב-behaviors שמועבר אל initializeUI(...).

כתובת אימייל וסיסמה

  1. מפעילים את האפשרות Email/Password (כתובת אימייל/סיסמה) במסוף Firebase.
  2. ‫Render של SignInAuthScreen או SignUpAuthScreen ב-React, של רכיבי sign-in-auth-screen או sign-up-auth-screen שנוצרו ב-Shadcn, או של fui-sign-in-auth-screen או fui-sign-up-auth-screen ב-Angular.
  1. מפעילים את האפשרויות Email/Password ו-Email link (passwordless sign-in) במסוף Firebase.
  2. ‫Render EmailLinkAuthScreen ב-React, רכיב email-link-auth-screen שנוצר ב-Shadcn או fui-email-link-auth-screen ב-Angular.
  3. במידת הצורך, משלימים את הכניסה באמצעות כתובת ה-URL הנוכחית בעזרת כלי העזר העיקריים.
import { completeEmailLinkSignIn } from '@firebase-oss/ui-core';

await completeEmailLinkSignIn(ui, window.location.href);

ספקי OAuth

‫FirebaseUI for Web תומך בלחצנים מובנים לספקים כמו Google,‏ Apple,‏ Facebook,‏ GitHub,‏ Microsoft ו-X/Twitter.

  1. מפעילים את הספק במסוף Firebase.
  2. מוסיפים את הדומיין של האפליקציה אל דומיינים מורשים במקומות שנדרש.
  3. מעבדים את OAuthScreen עם לחצני הספק הרצויים, כמו GoogleSignInButton,‏ AppleSignInButton,‏ FacebookSignInButton, GitHubSignInButton,‏ MicrosoftSignInButton או TwitterSignInButton ב-React, את המקבילות שנוצרו ב-shadcn באפליקציה, או fui-oauth-screen עם fui-google-sign-in-button, fui-apple-sign-in-button,‏ fui-facebook-sign-in-button, fui-github-sign-in-button,‏ fui-microsoft-sign-in-button או fui-twitter-sign-in-button ב-Angular.

מספר טלפון

  1. מפעילים את האפשרות טלפון במסוף Firebase.
  2. מוסיפים את הדומיין של האפליקציה לדומיינים מורשים.
  3. ‫Render של PhoneAuthScreen או PhoneAuthForm ב-React, של רכיבי phone-auth-screen או phone-auth-form שנוצרו ב-Shadcn, או של fui-phone-auth-screen ב-Angular.

אופציונלי: הגדרת מדינות מורשות, מדינת ברירת מחדל או התנהגות reCAPTCHA:

import {
  countryCodes,
  initializeUI,
  recaptchaVerification,
} from '@firebase-oss/ui-core';

const ui = initializeUI({
  app,
  behaviors: [
    countryCodes({
      allowedCountries: ['GB', 'US', 'FR'],
      defaultCountry: 'GB',
    }),
    recaptchaVerification({
      size: 'compact',
      theme: 'light',
    }),
  ],
});

התאמה אישית

הגדרת אופן הפעולה של אימות משותף ב-behaviors שמועבר אל initializeUI(...).

דרישה להזין שם שיוצג במהלך ההרשמה

import { initializeUI, requireDisplayName } from '@firebase-oss/ui-core';

const ui = initializeUI({
  app,
  behaviors: [requireDisplayName()],
});

שדרוג משתמשים אנונימיים

אפשר להשתמש בהתנהגות autoUpgradeAnonymousUsers(...) כדי למזג סשן אנונימי עם חשבון מחובר.

import {
  autoUpgradeAnonymousUsers,
  initializeUI,
} from '@firebase-oss/ui-core';

const ui = initializeUI({
  app,
  behaviors: [
    autoUpgradeAnonymousUsers({
      async onUpgrade(ui, oldUserId, credential) {
        // Migrate or merge user data here if needed.
      },
    }),
  ],
});

פרטים נוספים בנושא העברה (מיגרציה) זמינים במאמר MIGRATION.md.

כניסה

מעבדים את מסך האימות הרצוי ומטפלים בהצלחה בקריאות חוזרות (callback) של רכיבים או בפלט של Angular.

React

```tsx import { SignInAuthScreen } from '@firebase-oss/ui-react'; import { useNavigate } from 'react-router';

export function SignInPage() { const navigate = useNavigate();

‪return ( { navigate('/dashboard'); }} /> ); } ```

Shadcn

‫shadcn משתמש באותו זמן ריצה ובאותו תהליך כמו React. ההבדל היחיד הוא שאתם מייבאים את הרכיב שנוצר מהאפליקציה שלכם במקום מ-@firebase-oss/ui-react:

```tsx import { SignInAuthScreen } from '@/components/sign-in-auth-screen'; import { useNavigate } from 'react-router';

export function SignInPage() { const navigate = useNavigate();

‪return ( { navigate('/dashboard'); }} /> ); } ```

Angular

import { Component } from '@angular/core';
import { Router } from '@angular/router';
import { SignInAuthScreenComponent } from '@firebase-oss/ui-angular';
import type { User } from '@angular/fire/auth';

@Component({
  selector: 'app-sign-in-page',
  standalone: true,
  imports: [SignInAuthScreenComponent],
  template: `
    <fui-sign-in-auth-screen (signIn)="onSignIn($event)" />
  `,
})
export class SignInPageComponent {
  constructor(private router: Router) {}

  onSignIn(user: User) {
    this.router.navigate(['/dashboard']);
  }
}

יציאה מהחשבון

כדי להוציא משתמשים מהחשבון, משתמשים ב-API הרגיל של אימות ב-Firebase להוצאת משתמשים מהחשבון:

import { getAuth, signOut } from 'firebase/auth';

const auth = getAuth(app);
await signOut(auth);

ספקי OAuth: חלון קופץ לעומת הפניה אוטומטית

בוחרים את תהליך הכניסה של הספק עם התנהגויות:

  • providerPopupStrategy() לתהליכים קופצים
  • providerRedirectStrategy() לזרימות הפניה אוטומטית

החלון הקופץ הוא ברירת המחדל, לכן צריך להגדיר הפניה אוטומטית באופן מפורש:

import { initializeUI, providerRedirectStrategy } from '@firebase-oss/ui-core';

const ui = initializeUI({
  app,
  behaviors: [providerRedirectStrategy()],
});

כדי לעבד לחצני OAuth, מוסיפים אותם למסך הספציפי לפלטפורמה.

React

import {
  GitHubSignInButton,
  GoogleSignInButton,
  OAuthScreen,
} from '@firebase-oss/ui-react';

export function OAuthPage() {
  return (
    <OAuthScreen>
      <GoogleSignInButton />
      <GitHubSignInButton />
    </OAuthScreen>
  );
}

Shadcn

import { GitHubSignInButton } from '@/components/github-sign-in-button';
import { GoogleSignInButton } from '@/components/google-sign-in-button';
import { OAuthScreen } from '@/components/oauth-screen';

export function OAuthPage() {
  return (
    <OAuthScreen>
      <GoogleSignInButton />
      <GitHubSignInButton />
    </OAuthScreen>
  );
}

Angular

import { Component } from '@angular/core';
import {
  GithubSignInButtonComponent,
  GoogleSignInButtonComponent,
  OAuthScreenComponent,
} from '@firebase-oss/ui-angular';

@Component({
  selector: 'app-oauth-page',
  standalone: true,
  imports: [
    OAuthScreenComponent,
    GoogleSignInButtonComponent,
    GithubSignInButtonComponent,
  ],
  template: `
    <fui-oauth-screen>
      <fui-google-sign-in-button />
      <fui-github-sign-in-button />
    </fui-oauth-screen>
  `,
})
export class OAuthPageComponent {}

Google One Tap

כדי להפעיל את המנגנון 'לחיצה אחת' של Google, משתמשים בהתנהגות oneTapSignIn(...):

import { initializeUI, oneTapSignIn } from '@firebase-oss/ui-core';

const ui = initializeUI({
  app,
  behaviors: [
    oneTapSignIn({
      clientId: 'YOUR_GOOGLE_WEB_CLIENT_ID',
      autoSelect: false,
      cancelOnTapOutside: false,
    }),
  ],
});

מוודאים שהכניסה באמצעות חשבון Google מופעלת במסוף Firebase, ואז מעתיקים את מזהה לקוח האינטרנט מהגדרות ספק Google.

תנאים והגבלות ומדיניות פרטיות

מצרפים קישורים למדיניות דרך ההגדרה של ספק הפלטפורמה.

React

```tsx import { FirebaseUIProvider } from '@firebase-oss/ui-react';

‪<FirebaseUIProvider ui={ui} policies={{ termsOfServiceUrl: 'https://example.com/terms', privacyPolicyUrl: 'https://example.com/privacy', }}

{children} ; ```

Shadcn

משתמשים באותה הגדרה של FirebaseUIProvider כמו ב-React.

Angular

import { type ApplicationConfig } from '@angular/core';
import { provideFirebaseUIPolicies } from '@firebase-oss/ui-angular';

export const appConfig: ApplicationConfig = {
  providers: [
    provideFirebaseUIPolicies(() => ({
      termsOfServiceUrl: 'https://example.com/terms',
      privacyPolicyUrl: 'https://example.com/privacy',
    })),
  ],
};

תרגומים

‫FirebaseUI for Web תומך בהתאמה לשוק המקומי באמצעות @firebase-oss/ui-translations.

import { initializeUI } from '@firebase-oss/ui-core';
import { registerLocale } from '@firebase-oss/ui-translations';

const enUsCustom = registerLocale('en-US', {
  labels: {
    signIn: 'Continue',
  },
});

const ui = initializeUI({
  app,
  locale: enUsCustom,
});

השלבים הבאים