# Firebase Session

> Learn how to manage user logins and sessions with the Firebase Session component in PandaSuite.

https://docs.pandasuite.com/essentials/components/firebase-session/

**The Firebase Session component allows you to manage user logins and sessions within your PandaSuite application. With this component, you can easily integrate Firebase authentication and associate specific data with each user, such as a score, progress, or access type.** This component can be used with or without a user interface, depending on your needs.

## Enable Authentication via Firebase

Firebase is Google's mobile platform that enables the creation of a scalable and high-performance backend, primarily dedicated to mobile applications. The backend represents the server side of the application, handling responsibilities such as authentication, storage, notifications, etc.

> **Info**
>
> You need to have created a Firebase project for your application. Follow [this
> tutorial](https://docs.pandasuite.com/essentials/integrations/create-a-firebase-project/) to create a new
> project, then follow the instructions below.

### Enable Email/Password Login

Add an authentication method for your application.

- Go to **Authentication** and click on **Get Started**.
- In the **Sign-in method** tab, select **Email/Password** and click on **Enable**.
- If you want a passwordless flow in headless mode, also enable **Email link (passwordless sign-in)** in the same panel.

[Image: Sign-in method tab in Firebase: Email/Password and Email link (passwordless sign-in) are both enabled]

You now have an email and password authentication procedure. If **Email link (passwordless sign-in)** is also enabled, the **Firebase Session** component can request and complete a passwordless sign-in from a custom flow.

### Authorize your app domain

Firebase only sends email actions to domains it trusts.

- Go to **Authentication** and open **Settings**.
- In **Authorized domains**, add the domain used by your PandaSuite web app or landing page.
- Make sure the domain used in **Continue URL** is listed here before requesting an email-link sign-in.

[Image: Authorized domains in the Authentication settings of Firebase, including localhost, viewer.pandasuite.com and app.pandasuite.com]

> **Info**
>
> `localhost` is usually available for testing. In production, add each HTTPS
> domain or subdomain separately.

### Configure Cloud Firestore

Cloud Firestore is a database specific to Firebase. It allows you to associate data with your users.

- Go to the **Firestore Database** tab. Click on **Create Database**.

[Image: Cloud Firestore page of the Firebase console, with the Create Database button that starts the database setup]

- Choose the **Start in test mode** option.

[Image: Create Database window in Firebase: Start in test mode selected, with a warning that the data stays open for 30 days]

[Image: New Cloud Firestore database, still empty, in the Firebase console, with the Rules tab used in the next step]

- Go to the **Rules** tab: you need to update the security rules to avoid being blocked after 30 days. Copy and paste the code below:

```
rules_version = '2';
service cloud.firestore {
  match /databases/{database}/documents {
    match /users/{userId} {
      allow read, write: if request.auth.uid == userId
    }
  }
}
```

[Image: Rules tab of Cloud Firestore with the rules pasted: each user can read and write only their document in users]

Your Cloud Firestore configuration is ready.

## Configure the Firebase Session Component

Click on Components and choose **Firebase Session**. To make the component accessible throughout the application, insert it at the project level.

In PandaSuite Studio, the component editor includes two helpful tabs:

- **Test Session:** Sign in with a Firebase user to inspect the loaded Cloud Firestore document.
- **Default user data:** Prepare the data structure that should be created for each new user.

### Project ID and API Key

In the properties, copy/paste the **Project ID** and the **API Key** from the Firebase console.

[Image: Firebase Session component at project level in PandaSuite Studio: its API Key and Project ID fields, still empty, are framed]

These details are available in the **Project Settings** on Firebase.

[Image: Gear menu next to Project Overview in the Firebase console, open on Project Settings]

[Image: General settings of the Firebase project, with the Project ID and the Web API Key circled in red, to copy into PandaSuite]

### Choose the login interface

After configuring **Firebase Session**, choose how users will start their session:

- Use the [Authentication](https://docs.pandasuite.com/essentials/components/authentication/) component when you want PandaSuite's ready-to-use email/password sign-up and login form. It connects to **Firebase Session** but does not request or complete passwordless email-link sign-in.
- Use **Firebase Session** in headless mode when you need a custom interface, custom buttons, or passwordless email-link sign-in. In this case, build the screen yourself with components such as [Text Input](https://docs.pandasuite.com/essentials/components/text-input/), buttons, and text, then trigger **Firebase Session** actions.

### Force Authentication After (hours)

This option specifies the number of hours (after identification) during which the session remains valid, even without an internet connection. Beyond this number of hours, an internet connection will be required to continue. When the session is still valid, the user will not need to log in again. By default, a value of 0 creates an infinite session.

### Enforce email verification

This is an additional email validation step where the user receives a confirmation email with a link. This step is required before accessing the application.

> **Info**
>
> Firebase sends these account emails itself, such as the verification message.
> To brand them, open the **Templates** tab under **Authentication** in the
> Firebase console, where you can set the sender name, reply-to address, subject,
> and language. The body layout stays mostly fixed, so for fully custom emails you
> need to send them from your own email service.

### Default user data

Open the **Default user data** tab to define the document created in Cloud Firestore for each new user when they register.

Use this tab to prepare nested objects, arrays, or PandaSuite collections before the first sign-in. In Studio, it can also reuse data already available in your project, including collections. This makes it easier to initialize structured user data without manually typing every identifier.

Values added later during registration, such as **Traits** in headless mode or **Advanced user fields** in the [Authentication](https://docs.pandasuite.com/essentials/components/authentication/) component, are merged into this default structure.

When a user completes a passwordless email-link sign-in in headless mode, PandaSuite also tries to merge this default structure and store the user's email in the same document. If Firestore cannot write the document, the sign-in can still succeed and **Modify Data Error** is triggered.

To update this user document later from the app, see [Save user data in Firebase](https://docs.pandasuite.com/essentials/integrations/save-user-data-in-firebase/).

When a new user signs up, you should now see this default structure in that user's document in Cloud Firestore.

## Trigger an Action Based on User's Connection Status

To trigger an action based on the session state, select the Firebase Session component and add an action. Choose from the following triggers:

- **User Signed In:** The user session is valid. This trigger can be used to proceed to the next screen if the user is logged in.
- **User Signed Out:** The user session has expired. This can redirect the user to the login screen.

[Image: Triggers of the Firebase Session component: User signed in and User signed out are framed, before the error triggers]

You can also disconnect the user: **Interact with a component** > **Firebase Session** > **Sign Out**.

## Manage Your Users

You can manage your users directly on Firebase. Go to **Authentication** and the **Users** tab to access the user database. You can view user email, creation date, last login date, and unique user ID.

You can also [associate data with your users](https://docs.pandasuite.com/essentials/integrations/save-user-data-in-firebase/), such as a score, progress, or profile.

## Session Management Without User Interface (Headless Usage)

If you want to design a fully customized interface, you can use **Firebase Session** without a visual interface. This headless usage allows you to manage sessions in the background while building a tailored UI.

Features available in headless usage:

- **Email and password authentication:** You can integrate [Text Input](https://docs.pandasuite.com/essentials/components/text-input/) fields to enter credentials, then trigger **Interact with a component** > **Firebase Session** > **Sign In with Email and Password** or **Register with Email and Password**.

[Image: Sign In with Email and Password action on a button tap: Email and Password bound to the values of two Text Input fields]

- **Passwordless email link sign-in:**

  This flow does not use the [Authentication](https://docs.pandasuite.com/essentials/components/authentication/) component. Build a small screen with a [Text Input](https://docs.pandasuite.com/essentials/components/text-input/) for the email, a button to request the link, and a message area to guide the user.

  **Step 1. Request the link:** ask for the user's email, then trigger **Interact with a component** > **Firebase Session** > **Request Email Link Sign In**. Bind both **Email** and an authorized **Continue URL**.

  **Step 2. Complete sign-in:** when the link opens your app again, trigger **Interact with a component** > **Firebase Session** > **Complete Email Link Sign In** with the same email and the full callback URL.

  In a web app, you can bind the callback URL from **Project** → **Context** → **Launch** → **URL**. If the link is opened on another device, ask the user to enter the same email again before completing the sign-in. Use **Email Link Requested**, **Email Link Request Error**, and **Sign In Error** to guide the user through the flow.

- **Login with a custom token:** Ideal for systems where the backend generates secure tokens. Trigger **Interact with a component** > **Firebase Session** > **Sign In with Custom Token**.

[Image: Interact with a component menu for Firebase Session, with the Sign In with Custom Token action highlighted]

- **Registration with custom fields:** If you build your own headless sign-up flow, the **Traits** field lets you pass additional values during registration. Use it for advanced cases where you need to enrich the user document outside the standard [Authentication](https://docs.pandasuite.com/essentials/components/authentication/) form.

[Image: Register with Email and Password action: credentials bound to input fields, plus a Traits field for extra values]

- **Error management:** When an error occurs, such as a poorly formatted email, the **Sign In Error** or **Register Error** event captures the error message. You can store this message in a variable and display it using a [Condition](https://docs.pandasuite.com/essentials/components/condition/) or Text component.

[Image: Firebase Session triggers: User Signed In, User Signed Out, Sign In Error and Register Error]