Skip to main content

Firebase Installations

To start using the Firebase Installations package within your project, import it at the top of your project files:

import 'package:flutterfire_installations/flutterfire_installations.dart';

Before using Firebase Installations, you must first have ensured you have initialized FlutterFire.

To create a new Installations instance, call the instance getter on FirebaseAppInstallations:

FirebaseAppInstallations installations = FirebaseAppInstallations.instance;

By default, this allows you to interact with Installations using the default Firebase App used whilst installing FlutterFire on your platform. If however you'd like to use a secondary Firebase App, use the instanceFor method:

FirebaseApp secondaryApp = Firebase.app('SecondaryApp');
FirebaseAppInstallations installations = FirebaseAppInstallations.instanceFor(app: secondaryApp);

Delete a Firebase installation#

Data tied to a Firebase installation is generally not personally identifying. Still, it can be helpful to give users an option to manage and delete this data.

Firebase installation IDs are different for every installation of every application; different applications on the same device have different Firebase installation IDs. Firebase installation IDs identify app installations and data tied to those app installations.

When you delete an installation ID, the data tied to that installation ID is removed from live and backup systems of all Firebase services that use Firebase installation IDs to identify installations within 180 days. This process is described at a high level in Google’s statement on deletion and retention.

Unless you disable all FID-generating services in your app, FIS creates a new ID within a few days. Firebase considers the newly-created ID to be a new Firebase installation, and doesn't associate it with the previous ID or data in any way.

To delete an FID, call the delete method on the FirebaseAppInstallations instance:

await FirebaseAppInstallations.instance.delete();

Retrieve client identifiers#

If you have a requirement to identify particular installations of your app, you can do so by retrieving the Firebase installation ID. For example, to perform testing during Firebase In-App Messaging development, you can identify and target the correct test device using its Firebase installation ID.

To get the Firebase installation ID, call the getId method on the FirebaseAppInstallations instance:

String id = await FirebaseAppInstallations.instance.getId();

Retrieve installation auth tokens#

Firebase services can authenticate Firebase installations with auth tokens retrieved from FIS. For example, when designing A/B tests for Remote Config, you can authenticate a targeted test device using an installation auth token.

An installation auth token is a short-lived bearer token in JSON web token (JWT) format containing the following information for an installation:

  • The Firebase installation ID
  • The associated project (projectNumber)
  • The associated Firebase application ID (appId)
  • The token's expiration date

An installation auth token cannot be revoked, and remains valid until its expiration date. The default token lifetime is one week.

To retrieve an installation auth token:

String token = await FirebaseAppInstallations.instance.getToken();

Optionally, you can force a token refresh when called:

String token = await FirebaseAppInstallations.instance.getToken(true);

Monitor the Firebase Installation ID#

During the normal operation of an app, Firebase installation IDs (FIDs) don't require special monitoring. However, apps that explicitly retrieve and use FIDs should add logic to monitor the potential deletion or rotation of the FID. Here are some cases where FIDs could be deleted or rotated:

  • Uninstallation or re-installation of the app, for instance when an end user installs on a new device.
  • The end user clears the cache of the app or the device.
  • FID deletion is triggered in the backend due to app inactivity (currently the threshold for this is 270 days of inactivity).

When apps experience a FID rotation or deletion in these kinds of cases, they are assigned a new FID. Also, the installation auth token associated with a deleted FID is deleted, regardless of its own maturity, and is replaced with a new installation auth token.

Apps can monitor these changes and respond accordingly.

To monitor the FID token, listen to the Stream returned from the onIdChange getter:

FirebaseAppInstallations.instance.onIdChange.listen((token) {
print('FID token: $token');
});