--- title: Capacitor Remote Config Plugin for Android, iOS & Web description: Unofficial Capacitor plugin for Firebase Remote Config SDK to manage app configurations and feature flags remotely. tags: - Android - iOS - Web search: boost: 2 faq: true github_repo: capawesome-team/capacitor-firebase npm_package: "@capacitor-firebase/remote-config" --- # Capacitor Firebase Remote Config Plugin Unofficial Capacitor plugin for [Firebase Remote Config](https://firebase.google.com/docs/remote-config).[^1]
Deliver Live Updates to your Capacitor app with Capawesome Cloud
## 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 | ## Installation You can use our **AI-Assisted Setup** to install the plugin. Add the [Capawesome Skills](https://github.com/capawesome-team/skills) to your AI tool using the following command: ```bash 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: ```bash npm install @capacitor-firebase/remote-config firebase npx cap sync ``` Add Firebase to your project if you haven't already ([Android](https://github.com/capawesome-team/capacitor-firebase/blob/main/docs/firebase-setup.md#android) / [iOS](https://github.com/capawesome-team/capacitor-firebase/blob/main/docs/firebase-setup.md#ios) / [Web](https://github.com/capawesome-team/capacitor-firebase/blob/main/docs/firebase-setup.md#web)). ### Android Google Analytics is required for the [conditional targeting of app instances](https://firebase.google.com/docs/remote-config/parameters#conditions_rules_and_conditional_values) to user properties and audiences. Make sure that you install the [Capacitor Firebase Analytics](https://github.com/capawesome-team/capacitor-firebase/blob/main/packages/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](https://github.com/capawesome-team/capacitor-firebase/issues/959): ```json { "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](https://github.com/robingenz/capacitor-firebase-plugin-demo) ## Starter templates The following starter templates are available: - [Ionstarter Angular Firebase](https://ionstarter.dev/) ## 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(...)`: ```typescript 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: ```typescript 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: ```typescript 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: ```typescript 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: ```typescript 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: ```typescript import { FirebaseRemoteConfig } from '@capacitor-firebase/remote-config'; const removeAllListeners = async () => { await FirebaseRemoteConfig.removeAllListeners(); }; ``` ## API * [`activate()`](#activate) * [`fetchAndActivate()`](#fetchandactivate) * [`fetchConfig(...)`](#fetchconfig) * [`getBoolean(...)`](#getboolean) * [`getNumber(...)`](#getnumber) * [`getString(...)`](#getstring) * [`getAll()`](#getall) * [`getInfo()`](#getinfo) * [`setMinimumFetchInterval(...)`](#setminimumfetchinterval) * [`setCustomSignals(...)`](#setcustomsignals) * [`setDefaults(...)`](#setdefaults) * [`setSettings(...)`](#setsettings) * [`addConfigUpdateListener(...)`](#addconfigupdatelistener) * [`removeConfigUpdateListener(...)`](#removeconfigupdatelistener) * [`removeAllListeners()`](#removealllisteners) * [Interfaces](#interfaces) * [Type Aliases](#type-aliases) * [Enums](#enums) ### activate() ```typescript activate() => Promise ``` Make the last fetched configuration available to the getters. **Since:** 1.3.0 -------------------- ### fetchAndActivate() ```typescript fetchAndActivate() => Promise ``` Perform fetch and activate operations. **Since:** 1.3.0 -------------------- ### fetchConfig(...) ```typescript fetchConfig(options?: FetchConfigOptions | undefined) => Promise ``` Fetch and cache configuration from the Remote Config service. | Param | Type | | ------------- | ----------------------------------------------------------------- | | **`options`** | FetchConfigOptions | **Since:** 1.3.0 -------------------- ### getBoolean(...) ```typescript getBoolean(options: GetBooleanOptions) => Promise ``` Get the value for the given key as a boolean. | Param | Type | | ------------- | ------------------------------------------------- | | **`options`** | GetOptions | **Returns:** Promise<GetBooleanResult> **Since:** 1.3.0 -------------------- ### getNumber(...) ```typescript getNumber(options: GetNumberOptions) => Promise ``` Get the value for the given key as a number. | Param | Type | | ------------- | ------------------------------------------------- | | **`options`** | GetOptions | **Returns:** Promise<GetNumberResult> **Since:** 1.3.0 -------------------- ### getString(...) ```typescript getString(options: GetStringOptions) => Promise ``` Get the value for the given key as a string. | Param | Type | | ------------- | ------------------------------------------------- | | **`options`** | GetOptions | **Returns:** Promise<GetStringResult> **Since:** 1.3.0 -------------------- ### getAll() ```typescript getAll() => Promise ``` Get all the values from the Remote Config service. **Returns:** Promise<GetAllResult> **Since:** 8.3.0 -------------------- ### getInfo() ```typescript getInfo() => Promise ``` Get information about the last fetch operation. **Returns:** Promise<GetInfoResult> **Since:** 7.5.0 -------------------- ### setMinimumFetchInterval(...) ```typescript setMinimumFetchInterval(options: SetMinimumFetchIntervalOptions) => Promise ``` Set the minimum fetch interval. Only available for Web. | Param | Type | | ------------- | ----------------------------------------------------------------------------------------- | | **`options`** | SetMinimumFetchIntervalOptions | **Since:** 1.3.0 -------------------- ### setCustomSignals(...) ```typescript setCustomSignals(options: SetCustomSignalsOptions) => Promise ``` 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(...) ```typescript setDefaults(options: SetDefaultsOptions) => Promise ``` Sets config defaults for parameter keys and values in the default namespace config. | Param | Type | | ------------- | ----------------------------------------------------------------- | | **`options`** | SetDefaultsOptions | **Since:** 8.3.0 -------------------- ### setSettings(...) ```typescript setSettings(options: SetSettingsOptions) => Promise ``` Set the remote config settings. On Android, the settings values are persisted in SharedPreferences. | Param | Type | | ------------- | ----------------------------------------------------------------- | | **`options`** | SetSettingsOptions | **Since:** 6.2.0 -------------------- ### addConfigUpdateListener(...) ```typescript addConfigUpdateListener(callback: AddConfigUpdateListenerOptionsCallback) => Promise ``` 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(...) ```typescript removeConfigUpdateListener(options: RemoveConfigUpdateListenerOptions) => Promise ``` Remove a listener for the config update event. Only available for Android and iOS. | Param | Type | | ------------- | ----------------------------------------------------------------------------------------------- | | **`options`** | RemoveConfigUpdateListenerOptions | **Since:** 5.4.0 -------------------- ### removeAllListeners() ```typescript removeAllListeners() => Promise ``` 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](#fetch-and-activate-the-configuration) 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](https://github.com/capawesome-team/capacitor-firebase/blob/main/packages/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](https://capawesome.io/docs/sdks/capacitor/firebase/analytics/): Log events and user properties with Firebase Analytics. - [Live Update](https://capawesome.io/docs/sdks/capacitor/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](https://cloud.capawesome.io/newsletter/). ## Changelog See [CHANGELOG.md](https://github.com/capawesome-team/capacitor-firebase/blob/main/packages/remote-config/CHANGELOG.md). ## License See [LICENSE](https://github.com/capawesome-team/capacitor-firebase/blob/main/packages/remote-config/LICENSE). [^1]: This project is not affiliated with, endorsed by, sponsored by, or approved by Google LLC or any of their affiliates or subsidiaries.