Check out what’s new from Firebase at Google I/O 2022. Learn more

Remote Config Templates and Versioning

The Remote Config template is the server-side set of JSON-formatted parameters and conditions that you have created for your Firebase project. You can modify and manage the template using the Firebase console, which displays the contents of the template in graphical format in the Parameters and Conditions tabs. You can also use the Remote Config backend APIs or the Firebase CLI to modify and manage your config.

Here's an example of a template file:

  {
    "conditions": [
      {
        "name": "ios",
        "expression": "device.os == 'ios'"
      }
    ],
    "parameters": {
      "welcome_message": {
        "defaultValue": {
          "value": "Welcome to this sample app"
        },
        "conditionalValues": {
          "ios": {
            "value": "Welcome to this sample iOS app"
          }
        }
      },
      "welcome_message_caps": {
        "defaultValue": {
          "value": "false"
        }
      },
      "header_text": {
        "defaultValue": {
          "useInAppDefault": true
        }
      }
    },
    "version": {
      "versionNumber": "28",
      "updateTime": "2020-05-14T18:39:38.994Z",
      "updateUser": {
        "email": "user@google.com"
      },
      "updateOrigin": "CONSOLE",
      "updateType": "INCREMENTAL_UPDATE"
    }
  }

Each time you update parameters, Remote Config creates a new versioned Remote Config template and stores the previous template as a version that you can retrieve or roll back to as needed. Version numbers are incremented sequentially from the initial value stored by Remote Config. All templates include a version field as shown, containing metadata about that specific version.

With the Firebase console, the Firebase CLI, or the Remote Config backend APIs, you can perform these version management tasks:

  • List all stored template versions
  • Retrieve a specific version
  • Roll back to a specific version

As you manage Remote Config templates, keep the expiration threshold in mind: The current active Remote Config template in use by your app does not expire; however, if it is replaced by an update, the previous version will only be stored for 90 days, after which it will expire and cannot be retrieved. There is also a total limit of 300 stored versions. If you want to store or roll back to a template outside those limits, save and store it manually.

Manage Remote Config template versions

This section describes how to manage versions of your Remote Config template. For more detail on how to create, modify and save templates programmatically, see Modify Remote Config programmatically.

List all stored versions of the Remote Config template

You can retrieve a list of all stored versions of the Remote Config template. For example:

Node.js

function listAllVersions() {
  admin.remoteConfig().listVersions()
    .then((listVersionsResult) => {
      console.log("Successfully fetched the list of versions");
      listVersionsResult.versions.forEach((version) => {
        console.log('version', JSON.stringify(version));
      });
    })
    .catch((error) => {
      console.log(error);
    });
}

Java

ListVersionsPage page = FirebaseRemoteConfig.getInstance().listVersionsAsync().get();
while (page != null) {
  for (Version version : page.getValues()) {
    System.out.println("Version: " + version.getVersionNumber());
  }
  page = page.getNextPage();
}

// Iterate through all versions. This will still retrieve versions in batches.
page = FirebaseRemoteConfig.getInstance().listVersionsAsync().get();
for (Version version : page.iterateAll()) {
  System.out.println("Version: " + version.getVersionNumber());
}

REST

curl --compressed -D headers -H "Authorization: Bearer <var>token</var>" -X GET https://firebaseremoteconfig.googleapis.com/v1/projects/<var>my-project-id</var>/remoteConfig:listVersions

Firebase console

In the Parameters tab, select the "clock" icon displayed at top right. This opens the Change history page listing all stored template versions in a list menu at the right.

Details displayed for each stored version include information on whether the changes originated with the Console, with the REST API, from a rollback, or whether they were incremental changes from a forced save of the template.

Firebase CLI

firebase remoteconfig:versions:list

Use the --limit option to limit the number of versions being returned. Pass '0' to fetch all versions.

The list of templates includes metadata for all stored versions, including the time of the update, the user who made it, and whether it was made via the console or the REST API. Here is an example of a version element:

{
  "versions": [{
    "version_number": "6",
    "update_time": "2018-05-12T02:38:54Z",
    "update_user": {
      "email": "jane@developer.org",
    },
    "description": "One small change on the console",
    "origin": "CONSOLE",
    "update_type": "INCREMENTAL_UPDATE"
  }]

Retrieve a specific version of the Remote Config template

You can retrieve any specific stored version of the Remote Config template. For example:

Node.js

Pass getTemplate() without any arguments to retrieve the latest version of the template, or to retrieve a specific version, use getTemplateAtVersion().

// Get template version: 6
admin.remoteConfig().getTemplateAtVersion('6')
  .then((template) => {
    console.log("Successfully fetched the template with ETag: " + template.etag);
  })
  .catch((error) => {
    console.log(error);
  });

Java

Template template = FirebaseRemoteConfig.getInstance().getTemplateAtVersionAsync(versionNumber).get();
// See the ETag of the fetched template.
System.out.println("Successfully fetched the template with ETag: " + template.getETag());

REST

curl --compressed -D headers -H "Authorization: Bearer <var>token</var>" -X GET https://firebaseremoteconfig.googleapis.com/v1/projects/<var>my-project-id</var>/remoteConfig?version_number=6

The URL parameter ?version_number is valid only for GET operations; you cannot use it to specify version numbers for updates. A similar get request without the ?version_number parameter would retrieve the current active template.

Firebase console

By default, the details pane in the Change history tab displays the current active template. To view details for another version in the list, select it from the right menu.

You can view a detailed diff of the currently selected version and any other stored version by hovering over the context menu for any non-selected version and selecting Compare with selected version.

Firebase CLI

firebase remoteconfig:get -v VERSION_NUMBER

Optionally, you can write the output to a specified file with -o, FILENAME.

Roll back to a specific stored version of the Remote Config template

You can roll back to any stored version of the template. For example:

Node.js

// Roll back to template version: 6
admin.remoteConfig().rollback('6')
  .then((template) => {
    console.log("Successfully rolled back to template version 6.");
    console.log("New ETag: " + template.etag);
  })
  .catch((error) => {
    console.log('Error trying to rollback:', e);
  })

Java

try {
  Template template = FirebaseRemoteConfig.getInstance().rollbackAsync(versionNumber).get();
  System.out.println("Successfully rolled back to template version: " + versionNumber);
  System.out.println("New ETag: " + template.getETag());
} catch (ExecutionException e) {
  if (e.getCause() instanceof FirebaseRemoteConfigException) {
    FirebaseRemoteConfigException rcError = (FirebaseRemoteConfigException) e.getCause();
    System.out.println("Error trying to rollback template.");
    System.out.println(rcError.getMessage());
  }
}

REST

To roll back to a stored Remote Config template, issue an HTTP POST with the custom method :rollback and, in the request body, the specific version to apply. For example:

curl --compressed -D headers -H "Authorization: Bearer <var>token</var>" -H "Content-Type: application/json" -X POST https://firebaseremoteconfig.googleapis.com/v1/projects/<var>my-project-id</var>/remoteConfig:rollback -d '{"version_number": 6}'

The response contains the contents of the now-active stored template, with its new version metadata.

Firebase console

For previous template versions eligible for rollback, an option button to roll back to that version is displayed at top right of the Change history page. Click and confirm this only if you are sure you want to roll back to that version and use those values immediately for all apps and users.

Firebase CLI

firebase remoteconfig:rollback -v VERSION_NUMBER

Note that this rollback operation effectively creates a new numbered version. For example, rolling back from version 10 to version 6 effectively creates a new copy of version 6, differing from the original only in that its version number is 11. The original version 6 is still stored, assuming it has not reached its expiration, and version 11 becomes the active template.

Download Remote Config template defaults

Because your app may not always be connected to the Internet, you should configure client-side app default values for all Remote Config parameters. You should also periodically synchronize your app client default values and Remote Config backend default parameter values, because they may change over time.

As described in the platform-specific links at the end of this section, you can manually set these defaults in your app or you can streamline this process by downloading files that contain only the key-value pairs for all parameters and their default values in the active Remote Config template. You can then include this file in your project and configure your app to import these values.

You can download these files in XML format for Android apps, property list (plist) format for iOS apps, and JSON for web apps.

We recommend periodically downloading Remote Config defaults before any new app release to ensure that your app and the Remote Config backend stay in sync.

To download a file that contains template defaults:

REST

curl --compressed -D headers -H "Authorization: Bearer token -X GET https://firebaseremoteconfig.googleapis.com/v1/projects/my-project-id/remoteConfig:downloadDefaults?format=file_format'

Use XML, PLIST, or JSON as the format value, depending on which file format you want to download.

Firebase console

  1. In the Parameters tab, open the Menu, and select Download default values.
  2. When prompted, click the radio button that corresponds to the file format you want to download, and then click Download file.

For more information about importing Remote Config default values into your app, see: