firebase-remote-config-basics

# Firebase Remote Config Android Setup Guide

Important references:

- Refer to the `firebase-basics` skills, particularly those for project and app
  setup, before proceeding.

## Project and App Setup

Before you begin, ensure you have the following. If a `google-services.json`
file is present, then use that Firebase project and app. Otherwise you may need
to create them.

- **Firebase CLI**: Installed and logged in (see `firebase-basics`).
- **Firebase Project**: Created via
  `npx -y firebase-tools@latest projects:create` (see `firebase-basics`).
- **Firebase App**: Created via
  `npx -y firebase-tools@latest apps:create <IOS|ANDROID|WEB> <package-name-or-bundle-id>`

The `google-services.json` file must be present in the Android app's module
directory. If missing, get the config using the Firebase CLI:
`npx -y firebase-tools@latest apps:sdkconfig ANDROID <App-ID>`.

## Add Dependencies to Gradle Build

These changes are made to your Android project's Gradle files. Google Analytics
is highly recommended as it enables conditional targeting based on user
properties and audiences.

### Project-level `build.gradle.kts` (`<project>/build.gradle.kts`)

Ensure the Google Services plugin is in the `plugins` block:

```kotlin
plugins {
    // ... other plugins
    id("com.google.gms.google-services") version "4.4.0" apply false
}
```

### App-level `build.gradle.kts` (`<project>/<app-module>/build.gradle.kts`)

1. Add the Google Services plugin to the `plugins` block:

   ```kotlin
   plugins {
       // ... other plugins
       id("com.google.gms.google-services")
   }
   ```

1. Add the Firebase Remote Config and Analytics dependencies. Using the Firebase
   Bill of Materials (BoM) is the best practice for version management.

   ```kotlin
   dependencies {
       // ... other dependencies

       // Import the Firebase BoM
       implementation(platform("com.google.firebase:firebase-bom:32.7.0"))

       // Add the dependencies for Remote Config and Analytics
       implementation("com.google.firebase:firebase-config-ktx")
       implementation("com.google.firebase:firebase-analytics-ktx")
   }
   ```

## Follow up Steps

The following steps cover the essential patterns for using Remote Config
effectively.

### Set In-App Defaults

Define default values so your app has functional logic before it ever fetches a
template from the server. Create an XML file (e.g.,
`res/xml/remote_config_defaults.xml`):
`xml     <!-- Example Remote Config Defaults File -->     <?xml version="1.0" encoding="utf-8"?>     <defaultsMap>         <entry>             <key>welcome_message</key>             <value>Welcome to the app!</value>         </entry>         <entry>             <key>is_feature_enabled</key>             <value>false</value>         </entry>     </defaultsMap>     `
Then, initialize the SDK in your Activity or Application class:

````
```kotlin
val remoteConfig = Firebase.remoteConfig
remoteConfig.setDefaultsAsync(R.xml.remote_config_defaults)
```
````

### Fetch and Activate Values

To apply values from the cloud, you must fetch them and then activate them.
`kotlin     remoteConfig.fetchAndActivate()     .addOnCompleteListener(this) { task ->         if (task.isSuccessful) {             val updated = task.result             println("Config params updated: $updated")         } else {             println("Fetch failed")         }         // Access a value         val message = remoteConfig.getString("welcome_message")     }     `

# Firebase Remote Config iOS Setup Guide

Important references:

- Refer to the `firebase-basics` skills, particularly those for iOS setup,
  before proceeding.
- Refer to the `xcode-project-setup` skills.

## Project and App Setup

Use the `firebase-tools` CLI to set up the project if necessary.

1. **Find Bundle ID:** Read the Xcode project to find the iOS bundle ID. Check
   the `PRODUCT_BUNDLE_IDENTIFIER` value in the `.pbxproj` file or the
   `Info.plist` file.
1. **Create Firebase Project:** If no project exists, create one:
   `npx -y firebase-tools@latest projects:create <project-id> --display-name="My Awesome App"`
1. **Create Firebase App:** Register the iOS app with the discovered bundle ID:
   `npx -y firebase-tools@latest apps:create IOS <bundle-id>`
1. **Link the GoogleService-Info.plist file:** Use the script in the
   `xcode-project-setup` skill to obtain the config and link.

## Add Swift Package Dependencies

Install the Remote Config and Analytics SDKs using the Swift package manager.

Install the `FirebaseRemoteConfig` and `FirebaseAnalytics` packages from the
[https://github.com/firebase/firebase-ios-sdk.git](https://github.com/firebase/firebase-ios-sdk.git)
repository.

## Initialize Firebase in App Code

Modify the application's entry point to initialize Firebase. Refer to the iOS
setup reference in the firebase-basics skill.

## Follow up Steps

The following steps cover the essential patterns for using Remote Config
effectively in your iOS app.

### Set In-App Defaults

Define default values so your app behaves as intended before it connects to the
backend. Create a property list file (e.g., RemoteConfigDefaults.plist):

````
```xml
<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
<plist version="1.0">
<dict>
    <key>welcome_message</key>
    <string>Welcome to the app!</string>
    <key>is_feature_enabled</key>
    <false/>
</dict>
</plist>
```
````

Then, initialize the SDK and set the defaults:

````
```swift
import FirebaseRemoteConfig

let remoteConfig = RemoteConfig.remoteConfig()
remoteConfig.setDefaults(fromPlist: "RemoteConfigDefaults")
```
````

### Fetch and Activate Values

To retrieve values from the cloud and apply them to your app:

````
```swift
remoteConfig.fetchAndActivate { (status, error) in
    if status == .successFetchedFromRemote || status == .successUsingPreFetchedData {
        print("Config fetched and activated!")
    } else {
        print("Config not fetched")
    }
    
    // Access a value
    let message = remoteConfig.configValue(forKey: "welcome_message").stringValue
}
```
````

---
name: firebase-remote-config-basics
description: >-
  Manages Firebase Remote Config templates, feature flags, loading strategies, and SDKs (Android, iOS). Use when downloading/deploying remoteconfig JSON templates, managing version history/feature flags, setting in-app defaults, fetchAndActivate(), real-time listeners, or SDK setup. Don't use for Firebase Hosting, Auth, Firestore, Data Connect, Crashlytics, or App Hosting.
compatibility: This skill is best used with the Firebase CLI, but does not require it. Firebase CLI can be accessed through `npx -y firebase-tools@latest`.
metadata:
  category: ApplicationDevelopment
---

# Remote Config

This skill provides a complete guide for getting started with Remote Config on
Android or iOS. Remote Config allows you to change the behavior and appearance
of your app without publishing an app update by maintaining a cloud-based
configuration template.

## Prerequisites

Provisioning Remote Config requires both a Firebase project and a Firebase app,
either Android or iOS. To manage the Remote Config template and conditions via
the command line, use the Firebase CLI. See the `firebase-basics` skill for
references on project initialization.

## Troubleshooting Execution

### Handling npx 403 Forbidden Errors

If `npx -y firebase-tools@latest` fails due to registry permissions (403 error):

1. **Inform the user**: "I am unable to fetch the latest Firebase tools via npx
   due to a registry error."
1. **Fallback**: Attempt to use the local `firebase` command directly if the
   user confirms it is installed globally (`npm install -g firebase-tools`).

### Handling Project Context Issues

If a command fails because "no active project is selected":

1. **Check login**: Run `npx -y firebase-tools@latest login:list`.
1. **Prompt for ID**: If logged in but no project is active, ask the user:
   "Please provide your Firebase Project ID to proceed."
1. **Use Flag**: Append `--project <PROJECT_ID>` to every subsequent command.

## SDK Setup

To learn how to set up Remote Config in your application code, choose your
platform:

- **Android**: [android_setup.md](references/android_setup.md)
- **iOS**: [ios_setup.md](references/ios_setup.md)

## Best Practices and Template Management

Follow these guidelines and use the associated CLI tools to ensure efficient and
safe use of Remote Config.

### Fetching Strategies

To optimize app performance and user experience, follow these recommended
patterns (see
[Loading Strategies](https://firebase.google.com/docs/remote-config/loading)):

- **Load new values for next startup**: The most effective pattern is to
  activate previously fetched values immediately on startup and fetch new values
  in the background to be used next time. This minimizes user wait time.
- **Real-time Updates**: Use the SDK's real-time listener to update the app
  instantly without a refresh when server-side configuration changes.

### Template Management via CLI

Use the following commands to manage your Remote Config template and version
history through the terminal:

### Template Management via CLI

Use the following commands to manage your Remote Config template and version
history through the terminal:

- **Get current template**: Save the remote template to a local JSON file for
  auditing or modification.

  ```bash
  npx -y firebase-tools@latest remoteconfig:get -o remote_config.json
  ```

- **Autonomous Editing & Discovery** : Modify the local `remote_config.json`
  directly. Determine the correct signal (e.g., device.country or percent) and
  update the "conditions" array and "parameters" map accordingly.

- **MANDATORY: User Review and Verification** : STOP and ask the user to verify
  your changes before proceeding to deployment.

  - Action: Inform the user: "I have prepared the changes in remote_config.json.
    Please review the file for accuracy. Once you are satisfied, tell me to
    'deploy' to make the changes live."

- **Deployment Orchestration** : To push changes, you must ensure the
  environment is configured for deployment.

  - Config Mapping: If a firebase.json file is missing, create one to map the
    local JSON to the Remote Config service:

  ```json
    { "remoteconfig": { "template": "remote_config.json" } }
  ```

  - Deploy: Execute the partial deployment command
    
    ```bash
    npx -y firebase-tools@latest deploy --only remoteconfig
    ```

- **Verification**: After deployment, verify the update by listing the version
  history.

  ```bash
  npx -y firebase-tools@latest remoteconfig:versions:list
  ```

The SDK provides a number of features to make your application dynamic and
responsive to user segments.

- **Set In-App Defaults**: Define baseline values to ensure the app functions
  offline or before the first fetch.
- **Fetch and Activate**: Retrieve values from the Firebase backend and apply
  them to the local UI/Logic.
- **Template Management**: Use the Firebase CLI to version-control, get, and
  deploy your config JSON files.