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. If you're using the Remote Config backend APIs to modify and manage your config, you'll work directly with a template file such as this example remote-config.json:

{
  "parameters":[
    {
      "key":"welcome_message",
      "value_options":[
        {
          "value":"Welcome to this sample app"
        }
      ]
    },
    {
      "key":"welcome_message_caps",
      "value_options":[
        {
          "value":"false"
        }
      ]
    }
  ],
  "version":{
    "version_number": "42",
    "update_time":"2018-05-11T18:46:40Z",
    "update_user":{
      "name":"Jane Developer",
      "email":"jane@developer.org",
      "imageUrl":"http://image.google.com/path-to-profile-photo-for-jane"
    },
    "description":"Adding welcome messages",
    "origin":"CONSOLE",
    "update_type":"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 either the Firebase console or the REST API, you can peform 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: 90 days from creation time, or 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. The current active Remote Config template in use by your app does not expire; however, if it has been active over 90 days since creation and is replaced by an update, it cannot be retrieved again (due to expiration).

Manage Remote Config template versions with the Firebase console

The Firebase console provides a graphical interface to enable listing template versions, viewing their details, and rolling back as needed. To perform these tasks:

  1. 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.

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

    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.

  3. 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.

  4. For previous template versions eligible for rollback, an option button to roll back to that version is displayed at top right of the 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.

Manage Remote Config template versions with the REST API

This section describes how to manage versions of your Remote Config template using the REST API. For more detail on how to create, modify and save templates programatically, see Use the Remote Config REST API.

List all stored versions of the Remote Config template

With the custom HTTP method :listVersions, you can retrieve a list of all stored versions of the Remote Config template. For example:

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

The response 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

By appending the URL parameter ?version_number, you can retrieve any stored version of the Remote Config template. For example:

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

This parameter 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, as described in Get JSON from the Remote Config backend.

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

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 token" -X POST https://firebaseremoteconfig.googleapis.com/v1/projects/my-project-id/remoteConfig:rollback -d '{"version_number": 6}'

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

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.