@capacitor-firebase/remote-config

Capacitor Firebase Remote Config Plugin

Unofficial Capacitor plugin for Firebase Remote Config.[^1]

Use Cases

The Firebase Remote Config plugin is typically used to change the behavior and appearance of your app without publishing an app update, for example:

• Feature flags: Roll out new features gradually by toggling boolean parameters remotely.
• Promotions: Activate sales or promotions remotely, for example via an is_sale parameter.
• Maintenance announcements: Inform users about upcoming maintenance without releasing a new app version.
• Real-time updates: React to configuration changes in real time using the config update listener.
• Default values: Provide in-app default values so your app behaves predictably before the first fetch.

Compatibility

Plugin Version	Capacitor Version	Status
8.x.x	>=8.x.x	Active support
7.x.x	7.x.x	Deprecated
6.x.x	6.x.x	Deprecated
5.x.x	5.x.x	Deprecated

Guides

• Feature Flags in a Capacitor App with Remote Config: Feature flags, staged rollouts, and real-time config updates with this plugin.
• How to Use Firebase in a Capacitor App: How feature flags plug into the rest of the family, including the Analytics audiences they target.

Installation

You can use our AI-Assisted Setup to install the plugin. Add the Capawesome Skills to your AI tool using the following command:

npx skills add capawesome-team/skills --skill capacitor-plugins

Then use the following prompt:

Use the `capacitor-plugins` skill from `capawesome-team/skills` to install the `@capacitor-firebase/remote-config` plugin in my project.

If you prefer Manual Setup, install the plugin by running the following commands and follow the platform-specific instructions below:

npm install @capacitor-firebase/remote-config firebase
npx cap sync

Add Firebase to your project if you haven't already (Android / iOS / Web).

Android

Google Analytics is required for the conditional targeting of app instances to user properties and audiences. Make sure that you install the Capacitor Firebase Analytics plugin in your project.

Variables

If needed, you can define the following project variable in your app’s variables.gradle file to change the default version of the dependency:

• $firebaseConfigVersion version of com.google.firebase:firebase-config (default: 23.0.1)

This can be useful if you encounter dependency conflicts with other plugins in your project.

iOS

Swift Package Manager

Add the following to your capacitor.config.json (or capacitor.config.ts) to avoid a SwiftPM package identity collision:

{
  "experimental": {
    "ios": {
      "spm": {
        "packageOptions": {
          "@capacitor-firebase/remote-config": {
            "symlink": true
          }
        }
      }
    }
  }
}

Attention: SPM packageOptions support requires Capacitor CLI 8.4.0+.

Configuration

No configuration required for this plugin.

Demo

A working example can be found here: robingenz/capacitor-firebase-plugin-demo

Starter templates

The following starter templates are available:

• Ionstarter Angular Firebase

Usage

The following examples show how to fetch and activate the configuration, read configuration values, configure the fetch behavior, set custom signals, and listen for configuration updates in real time.

Fetch and activate the configuration

Fetch the latest configuration from the Remote Config service and activate it to make it available to the getters. Use fetchAndActivate() to perform both operations at once. On Android and iOS, you can pass a minimum fetch interval to fetchConfig(...):

import { FirebaseRemoteConfig } from '@capacitor-firebase/remote-config';

const fetchConfig = async () => {
  await FirebaseRemoteConfig.fetchConfig({
    minimumFetchIntervalInSeconds: 1200,
  });
};

const activate = async () => {
  await FirebaseRemoteConfig.activate();
};

const fetchAndActivate = async () => {
  await FirebaseRemoteConfig.fetchAndActivate();
};

Read configuration values

Read the value for a given key as a boolean, number, or string:

import { FirebaseRemoteConfig } from '@capacitor-firebase/remote-config';

const getBoolean = async () => {
  const { value } = await FirebaseRemoteConfig.getBoolean({
    key: 'is_sale',
  });
  return value;
};

const getNumber = async () => {
  const { value } = await FirebaseRemoteConfig.getNumber({
    key: 'upcoming_maintenance',
  });
  return value;
};

const getString = async () => {
  const { value } = await FirebaseRemoteConfig.getString({
    key: 'license_key',
  });
  return value;
};

Configure the fetch behavior

Set the fetch timeout and the minimum fetch interval. During development, it's recommended to set a relatively low minimum fetch interval:

import { FirebaseRemoteConfig } from '@capacitor-firebase/remote-config';

const setSettings = async () => {
  await FirebaseRemoteConfig.setSettings({
    fetchTimeoutInSeconds: 10,
    minimumFetchIntervalInSeconds: 0,
  });
};

Set custom signals

Set custom signals for the app instance that can be used for targeting in Remote Config conditions. Signals with a null value will be removed:

import { FirebaseRemoteConfig } from '@capacitor-firebase/remote-config';

const setCustomSignals = async () => {
  await FirebaseRemoteConfig.setCustomSignals({
    customSignals: {
      city: 'Berlin',
      preferred_event_category: 'concerts',
    },
  });
};

Listen for configuration updates in real time

Add a listener for the config update event to be notified as soon as parameter values change. Only available on Android and iOS:

import { FirebaseRemoteConfig } from '@capacitor-firebase/remote-config';

const addConfigUpdateListener = async () => {
  const callbackId = await FirebaseRemoteConfig.addConfigUpdateListener(
    (event, error) => {
      if (error) {
        console.error(error);
      } else {
        console.log(event);
      }
    }
  );
  return callbackId;
};

const removeConfigUpdateListener = async (callbackId: string) => {
  await FirebaseRemoteConfig.removeConfigUpdateListener({
    callbackId,
  });
};

Remove all listeners

Remove all listeners that have been added for this plugin:

import { FirebaseRemoteConfig } from '@capacitor-firebase/remote-config';

const removeAllListeners = async () => {
  await FirebaseRemoteConfig.removeAllListeners();
};

API

• activate()
• fetchAndActivate()
• fetchConfig(...)
• getBoolean(...)
• getNumber(...)
• getString(...)
• getAll()
• getInfo()
• setMinimumFetchInterval(...)
• setCustomSignals(...)
• setDefaults(...)
• setSettings(...)
• addConfigUpdateListener(...)
• removeConfigUpdateListener(...)
• removeAllListeners()
• Interfaces
• Type Aliases
• Enums

activate()

activate() => Promise<void>

Make the last fetched configuration available to the getters.

Since: 1.3.0

---

fetchAndActivate()

fetchAndActivate() => Promise<void>

Perform fetch and activate operations.

Since: 1.3.0

---

fetchConfig(...)

fetchConfig(options?: FetchConfigOptions | undefined) => Promise<void>

Fetch and cache configuration from the Remote Config service.

Param	Type
options	FetchConfigOptions

Since: 1.3.0

---

getBoolean(...)

getBoolean(options: GetBooleanOptions) => Promise<GetBooleanResult>

Get the value for the given key as a boolean.

Param	Type
options	GetOptions

Returns: Promise<GetBooleanResult>

Since: 1.3.0

---

getNumber(...)

getNumber(options: GetNumberOptions) => Promise<GetNumberResult>

Get the value for the given key as a number.

Param	Type
options	GetOptions

Returns: Promise<GetNumberResult>

Since: 1.3.0

---

getString(...)

getString(options: GetStringOptions) => Promise<GetStringResult>

Get the value for the given key as a string.

Param	Type
options	GetOptions

Returns: Promise<GetStringResult>

Since: 1.3.0

---

getAll()

getAll() => Promise<GetAllResult>

Get all the values from the Remote Config service.

Returns: Promise<GetAllResult>

Since: 8.3.0

---

getInfo()

getInfo() => Promise<GetInfoResult>

Get information about the last fetch operation.

Returns: Promise<GetInfoResult>

Since: 7.5.0

---

setMinimumFetchInterval(...)

setMinimumFetchInterval(options: SetMinimumFetchIntervalOptions) => Promise<void>

Set the minimum fetch interval.

Only available for Web.

Param	Type
options	SetMinimumFetchIntervalOptions

Since: 1.3.0

---

setCustomSignals(...)

setCustomSignals(options: SetCustomSignalsOptions) => Promise<void>

Set custom signals for the app instance that can be used for targeting in Remote Config conditions.

Param	Type
options	SetCustomSignalsOptions

Since: 8.4.0

---

setDefaults(...)

setDefaults(options: SetDefaultsOptions) => Promise<void>

Sets config defaults for parameter keys and values in the default namespace config.

Param	Type
options	SetDefaultsOptions

Since: 8.3.0

---

setSettings(...)

setSettings(options: SetSettingsOptions) => Promise<void>

Set the remote config settings.

On Android, the settings values are persisted in SharedPreferences.

Param	Type
options	SetSettingsOptions

Since: 6.2.0

---

addConfigUpdateListener(...)

addConfigUpdateListener(callback: AddConfigUpdateListenerOptionsCallback) => Promise<CallbackId>

Add a listener for the config update event.

Only available for Android and iOS.

Param	Type
callback	AddConfigUpdateListenerOptionsCallback

Returns: Promise<string>

Since: 5.4.0

---

removeConfigUpdateListener(...)

removeConfigUpdateListener(options: RemoveConfigUpdateListenerOptions) => Promise<void>

Remove a listener for the config update event.

Only available for Android and iOS.

Param	Type
options	RemoveConfigUpdateListenerOptions

Since: 5.4.0

---

removeAllListeners()

removeAllListeners() => Promise<void>

Remove all listeners for this plugin.

Since: 5.4.0

---

Interfaces

FetchConfigOptions

Prop	Type	Description	Default	Since
minimumFetchIntervalInSeconds	number	Define the maximum age in seconds of an entry in the config cache before it is considered stale. During development, it's recommended to set a relatively low minimum fetch interval. Only available for Android and iOS.	43200	1.3.0

GetBooleanResult

Prop	Type	Description	Since
value	boolean	The value for the given key as a boolean.	1.3.0
source	GetValueSource	Indicates at which source this value came from.	1.3.0

GetOptions

Prop	Type	Description	Since
key	string	The key of the value to get.	1.3.0

GetNumberResult

Prop	Type	Description	Since
value	number	The value for the given key as a number.	1.3.0
source	GetValueSource	Indicates at which source this value came from.	1.3.0

GetStringResult

Prop	Type	Description	Since
value	string	The value for the given key as a string.	1.3.0
source	GetValueSource	Indicates at which source this value came from.	1.3.0

GetAllResult

Prop	Type	Description	Since
values	Record<string, GetAllResultValue>	The values for all keys.	8.3.0

GetAllResultValue

Prop	Type	Description	Since
value	string	The value as a string.	8.3.0
source	GetValueSource	Indicates at which source this value came from.	8.3.0

GetInfoResult

Prop	Type	Description	Since
lastFetchTime	number	The Unix timestamp in milliseconds of the last successful fetch, or -1 if no fetch has occurred or initialization is incomplete.	7.5.0
lastFetchStatus	LastFetchStatus	The status of the last fetch attempt.	7.5.0

SetMinimumFetchIntervalOptions

Prop	Type	Description	Default	Since
minimumFetchIntervalInSeconds	number	Define the maximum age in seconds of an entry in the config cache before it is considered stale. During development, it's recommended to set a relatively low minimum fetch interval.	43200	1.3.0

SetCustomSignalsOptions

Prop	Type	Description	Since
customSignals	Record<string, string | number | null>	The custom signals to set for the app instance. Signals with a null value will be removed.	8.4.0

SetDefaultsOptions

Prop	Type	Description	Since
defaults	Record<string, string | number | boolean>	Defines the dictionary of values to set as defaults.	8.3.0

SetSettingsOptions

Prop	Type	Description	Default	Since
fetchTimeoutInSeconds	number	Defines the maximum amount of milliseconds to wait for a response when fetching configuration from the Remote Config server.	60	6.2.0
minimumFetchIntervalInSeconds	number	Define the maximum age in seconds of an entry in the config cache before it is considered stale. During development, it's recommended to set a relatively low minimum fetch interval.	43200	6.2.0

AddConfigUpdateListenerOptionsCallbackEvent

Prop	Type	Description	Since
updatedKeys	string[]	Parameter keys whose values have been updated from the currently activated values.	5.4.0

RemoveConfigUpdateListenerOptions

Prop	Type	Description	Since
id	CallbackId	The id of the listener to remove.	5.4.0

Type Aliases

GetBooleanOptions

GetOptions

GetNumberOptions

GetOptions

GetStringOptions

GetOptions

AddConfigUpdateListenerOptionsCallback

(event: AddConfigUpdateListenerOptionsCallbackEvent | null, error: any): void

CallbackId

string

Enums

GetValueSource

Members	Value	Description	Since
Static	0	Indicates that the value returned is the static default value.	1.3.0
Default	1	Indicates that the value returned was retrieved from the defaults set by the client.	1.3.0
Remote	2	Indicates that the value returned was retrieved from the Firebase Remote Config Server.	1.3.0

LastFetchStatus

Members	Value
NoFetchYet	0
Success	1
Failure	2
Throttled	3

FAQ

Why do the getters return default values instead of the remote ones?

Fetched configuration values must be activated before they are available to the getters. Call fetchConfig(...) followed by activate(), or use fetchAndActivate() to perform both operations at once, as shown in the usage example above.

How often does the plugin fetch new configuration values?

Fetched configuration values are cached. The minimum fetch interval defines the maximum age in seconds of an entry in the config cache before it is considered stale, with a default of 43200 seconds (12 hours). During development, it's recommended to set a relatively low minimum fetch interval using setSettings(...) on Android and iOS or setMinimumFetchInterval(...) on Web.

How can I react to configuration changes in real time?

Use addConfigUpdateListener(...) to be notified as soon as parameter values change, including the keys whose values have been updated. This method is only available on Android and iOS. You can remove the listener again with removeConfigUpdateListener(...) or removeAllListeners().

Do I need the Firebase Analytics plugin to use Remote Config?

Google Analytics is only required for the conditional targeting of app instances to user properties and audiences. If you want to use conditions, make sure to also install the Capacitor Firebase Analytics plugin in your project.

How can I tell where a configuration value came from?

The getters return a source property in addition to the value. It indicates whether the value is the static default value, was retrieved from the defaults set by the client, or was retrieved from the Firebase Remote Config server.

Related Plugins

• Firebase Analytics: Log events and user properties with Firebase Analytics.
• Live Update: Update your app remotely in real-time without requiring users to download a new version from the app store.

Newsletter

Stay up to date with the latest news and updates about the Capawesome, Capacitor, and Ionic ecosystem by subscribing to our Capawesome Newsletter.

Changelog

See CHANGELOG.md.

License

See LICENSE.

[^1]: This project is not affiliated with, endorsed by, sponsored by, or approved by Google LLC or any of their affiliates or subsidiaries.