Manage Firebase installations

The Firebase installations service (FIS) provides a Firebase installation ID (FID) for each installed instance of a Firebase app. The Firebase installation ID is used internally by Firebase services such as In-App Messaging or Remote Config without requiring developers to interact directly with the FIS API. However, there are cases where app developers might want to directly call the FIS API, such as:

To delete a Firebase installation and data tied to the installation.
To retrieve identifiers (Firebase installation IDs) in order to target specific app installations.
To retrieve authentication tokens to authenticate Firebase installations.

To get started with directly calling the FIS API, add the SDK to your app.

Add the Firebase installations SDK to your app

iOS

Add the dependency for Firebase installations to your Podfile:
```
pod 'Firebase/Installations'
```
Run pod install and open the created .xcworkspace file.
Import the Firebase module in your UIApplicationDelegate:
Swift
```
import Firebase
```
Objective-C
```
@import Firebase;
```
Configure a FirebaseApp shared instance, typically in your app's application:didFinishLaunchingWithOptions: method:
Swift
```
// Use Firebase library to configure APIs
FirebaseApp.configure()
```
Objective-C
```
// Use Firebase library to configure APIs
[FIRApp configure];
```

Android

Add the dependency for the Firebase installations Android SDK to your module (app-level) Gradle file (usually app/build.gradle):

implementation 'com.google.firebase:firebase-installations:16.3.3'

JavaScript

Depending on how your web application is hosted, your configuration may be handled automatically or you may need to update your Firebase configuration object.

For example, if your dependencies are added in index.html, add the dependency in the <head> element:

<script src="/__/firebase/8.0.0/firebase-installations.js"></script>

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.

Delete an FID with a client API call

To delete FIDs generated by Firebase services, call the appropriate method from the Firebase installations SDK:

Swift

func delete(completion: @escaping (Error?) -> Void)

Objective-C

- (void)deleteWithCompletion:(nonnull void (^)(NSError *_Nullable))completion;

Java

FirebaseInstallations.getInstance().delete()
        .addOnCompleteListener(new OnCompleteListener<Void>() {
    @Override
    public void onComplete(@NonNull Task<Void> task) {
        if (task.isSuccessful()) {
            Log.d("Installations", "Installation deleted");
        } else {
            Log.e("Installations", "Unable to delete Installation");
        }
    }
});MainActivity.java

Kotlin+KTX

FirebaseInstallations.getInstance().delete().addOnCompleteListener { task ->
    if (task.isComplete) {
        Log.d("Installations", "Installation deleted")
    }  else {
        Log.e("Installations", "Unable to delete Installation")
    }
}MainActivity.kt

JavaScript

await firebase.installations().delete();index.js

Delete an FID with a server API call

To delete an FID with a server API call, add the Firebase Admin SDK to your server, if you haven't already.

Once the SDK is added, delete FIDs through a call to the deletion function in your language of choice (note: though these methods reflect Instance ID naming, they actually delete the FID when called with any current Firebase SDK).

Node.js

// An FID sent from a client service SDK
const idToDelete = 'eyJhbGciOiJFUzI1N_iIs5';

admin.instanceId().deleteInstanceId(idToDelete);

Java

// An FID sent from a client service SDK
String idToDelete = "eyJhbGciOiJFUzI1N_iIs5";

FirebaseInstanceId.getInstance().deleteInstanceIdAsync(idToDelete).get();

Python

  from firebase_admin import instance_id

  # An FID sent from a client service SDK
  id_to_delete = 'eyJhbGciOiJFUzI1N_iIs5'

  instance_id.delete_instance_id(id_to_delete)

Go

client, err := app.InstanceId(ctx)
if err != nil {
  log.Fatalln("error initializing client", err)
}

iidToDelete := "eyJhbGciOiJFUzI1N_iIs5"
if err := client.DeleteInstanceId(ctx, iidToDelete); err != nil {
  log.Fatalln("error deleting FID", err)
}

When you delete an Firebase installation ID with a server API call, Firebase services start the process to delete the data tied to that installation ID, stop accepting new data for that ID over the course of 1-2 days, and then notify the client app that the ID was deleted. Until Firebase notifies the client app, some of the app's services might still target the ID—for example, a Firebase installation might continue to receive FCM notifications for a few hours.

If you want to delete the current Firebase installation ID and immediately use Firebase services with a new, unrelated ID, use the client API to handle the deletion.

Retrieve client identifers

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 retrieve a Firebase installation ID:

Swift

Installations.installations().installationID { (id, error) in
  if let error = error {
    print("Error fetching id: \(error)")
    return
  }
  guard let id = id else { return }
  print("Installation ID: \(id)")
}AppDelegate.swift

Objective-C

[[FIRInstallations installations] installationIDWithCompletion:^(NSString *identifier, NSError *error) {
  if (error != nil) {
    NSLog(@"Error fetching Installation ID %@", error);
    return;
  }
  NSLog(@"Installation ID: %@", identifier);
}];ObjCSnippets.m

Java

FirebaseInstallations.getInstance().getId()
        .addOnCompleteListener(new OnCompleteListener<String>() {
    @Override
    public void onComplete(@NonNull Task<String> task) {
        if (task.isSuccessful()) {
            Log.d("Installations", "Installation ID: " + task.getResult());
        } else {
            Log.e("Installations", "Unable to get Installation ID");
        }
    }
});MainActivity.java

Kotlin+KTX

FirebaseInstallations.getInstance().id.addOnCompleteListener { task ->
    if (task.isSuccessful) {
        Log.d("Installations", "Installation ID: " + task.result)
    } else {
        Log.e("Installations", "Unable to get Installation ID")
    }
}MainActivity.kt

JavaScript

const installationId = await firebase.installations().getId();
console.log(installationId);index.js

Retrieve FIS 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 a FIS auth token.

FIS auth tokens are short-lived bearer tokens in JSON web token (JWT) format containing the following information for the installation:

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

FIS auth tokens cannot be revoked, and remain valid until their expiration date. The default token lifetime is one week.

To retrieve a FIS auth token:

Swift

Installations.installations().authTokenForcingRefresh(true, completion: { (token, error) in
  if let error = error {
    print("Error fetching token: \(error)")
    return
  }
  guard let token = token else { return }
  print("Installation auth token: \(token)")
})AppDelegate.swift

Objective-C

[[FIRInstallations installations] authTokenForcingRefresh:true
                                               completion:^(FIRInstallationsAuthTokenResult *result, NSError *error) {
  if (error != nil) {
    NSLog(@"Error fetching Installation token %@", error);
    return;
  }
  NSLog(@"Installation auth token: %@", [result authToken]);
}];ObjCSnippets.m

Java

FirebaseInstallations.getInstance().getToken(/* forceRefresh */true)
        .addOnCompleteListener(new OnCompleteListener<InstallationTokenResult>() {
    @Override
    public void onComplete(@NonNull Task<InstallationTokenResult> task) {
        if (task.isSuccessful() && task.getResult() != null) {
            Log.d("Installations", "Installation auth token: " + task.getResult().getToken());
        } else {
            Log.e("Installations", "Unable to get Installation auth token");
        }
    }
});MainActivity.java

Kotlin+KTX

FirebaseInstallations.getInstance().getToken(/* forceRefresh */ true)
    .addOnCompleteListener { task ->
        if (task.isSuccessful) {
            Log.d("Installations", "Installation auth token: " + task.result?.token)
        } else {
            Log.e("Installations", "Unable to get Installation auth token")
        }
    }MainActivity.kt

JavaScript

const installationToken = await firebase.installations()
    .getToken(/* forceRefresh */ true);
console.log(installationToken);index.js

Firebase installations and Instance ID

For data deletion as well as internal use, FIS is backward-compatible with the legacy identifier Firebase Instance ID. Deleting an IID is an alternative method of requesting data deletion with these Firebase SDKs:

iOS 6.14.0 and lower
Android SDKs earlier than February 27, 2020

If you want to request deletion of an installation with more recent iOS and Android SDKs, updating your code to use FIS is recommended but not required.

If your app currently uses the Instance ID SDK via an indirect dependency to retrieve IDs, you can either update your code to use Firebase installations instead or, alternatively, you could update your application to add a direct dependency on the Instance ID SDK.

Sep	OCT	Nov
	31
2019	2020	2021