Remote Config realtime for Web

common/api-review/remote-config.api.md

@@ -5,10 +5,23 @@
 ```ts
 
 import { FirebaseApp } from '@firebase/app';
+import { FirebaseError } from '@firebase/app';
 
 // @public
 export function activate(remoteConfig: RemoteConfig): Promise<boolean>;
 
+// @public
+export interface ConfigUpdate {
+    getUpdatedKeys(): Set<string>;
+}
+
+// @public
+export interface ConfigUpdateObserver {
+    complete: () => void;
+    error: (error: FirebaseError) => void;
+    next: (configUpdate: ConfigUpdate) => void;
+}
+
 // @public
 export interface CustomSignals {
     // (undocumented)
@@ -64,6 +77,9 @@ export function isSupported(): Promise<boolean>;
 // @public
 export type LogLevel = 'debug' | 'error' | 'silent';
 
+// @public
+export function onConfigUpdate(remoteConfig: RemoteConfig, observer: ConfigUpdateObserver): Promise<Unsubscribe>;
+
 // @public
 export interface RemoteConfig {
     app: FirebaseApp;
@@ -93,6 +109,9 @@ export function setCustomSignals(remoteConfig: RemoteConfig, customSignals: Cust
 // @public
 export function setLogLevel(remoteConfig: RemoteConfig, logLevel: LogLevel): void;
 
+// @public
+export type Unsubscribe = () => void;
+
 // @public
 export interface Value {
     asBoolean(): boolean;

docs-devsite/_toc.yaml

@@ -607,6 +607,10 @@ toc:
 - title: remote-config
   path: /docs/reference/js/remote-config.md
   section:
+  - title: ConfigUpdate
+    path: /docs/reference/js/remote-config.configupdate.md
+  - title: ConfigUpdateObserver
+    path: /docs/reference/js/remote-config.configupdateobserver.md
   - title: CustomSignals
     path: /docs/reference/js/remote-config.customsignals.md
   - title: FetchResponse

docs-devsite/remote-config.configupdate.md

@@ -0,0 +1,39 @@
+Project: /docs/reference/js/_project.yaml
+Book: /docs/reference/_book.yaml
+page_type: reference
+
+{% comment %}
+DO NOT EDIT THIS FILE!
+This is generated by the JS SDK team, and any local changes will be
+overwritten. Changes should be made in the source code at
+https://github.com/firebase/firebase-js-sdk
+{% endcomment %}
+
+# ConfigUpdate interface
+Contains information about which keys have been updated.
+
+<b>Signature:</b>
+
+```typescript
+export interface ConfigUpdate 
+```
+
+## Methods
+
+|  Method | Description |
+|  --- | --- |
+|  [getUpdatedKeys()](./remote-config.configupdate.md#configupdategetupdatedkeys) | Parameter keys whose values have been updated from the currently activated values. Includes keys that are added, deleted, or whose value, value source, or metadata has changed. |
+
+## ConfigUpdate.getUpdatedKeys()
+
+Parameter keys whose values have been updated from the currently activated values. Includes keys that are added, deleted, or whose value, value source, or metadata has changed.
+
+<b>Signature:</b>
+
+```typescript
+getUpdatedKeys(): Set<string>;
+```
+<b>Returns:</b>
+
+Set&lt;string&gt;
+

docs-devsite/remote-config.configupdateobserver.md

@@ -0,0 +1,59 @@
+Project: /docs/reference/js/_project.yaml
+Book: /docs/reference/_book.yaml
+page_type: reference
+
+{% comment %}
+DO NOT EDIT THIS FILE!
+This is generated by the JS SDK team, and any local changes will be
+overwritten. Changes should be made in the source code at
+https://github.com/firebase/firebase-js-sdk
+{% endcomment %}
+
+# ConfigUpdateObserver interface
+Observer interface for receiving real-time Remote Config update notifications.
+
+NOTE: Although an `complete` callback can be provided, it will never be called because the ConfigUpdate stream is never-ending.
+
+<b>Signature:</b>
+
+```typescript
+export interface ConfigUpdateObserver 
+```
+
+## Properties
+
+|  Property | Type | Description |
+|  --- | --- | --- |
+|  [complete](./remote-config.configupdateobserver.md#configupdateobservercomplete) | () =&gt; void | Called when the stream is gracefully terminated. |
+|  [error](./remote-config.configupdateobserver.md#configupdateobservererror) | (error: [FirebaseError](./util.firebaseerror.md#firebaseerror_class)<!-- -->) =&gt; void | Called if an error occurs during the stream. |
+|  [next](./remote-config.configupdateobserver.md#configupdateobservernext) | (configUpdate: [ConfigUpdate](./remote-config.configupdate.md#configupdate_interface)<!-- -->) =&gt; void | Called when a new ConfigUpdate is available. |
+
+## ConfigUpdateObserver.complete
+
+Called when the stream is gracefully terminated.
+
+<b>Signature:</b>
+
+```typescript
+complete: () => void;
+```
+
+## ConfigUpdateObserver.error
+
+Called if an error occurs during the stream.
+
+<b>Signature:</b>
+
+```typescript
+error: (error: FirebaseError) => void;
+```
+
+## ConfigUpdateObserver.next
+
+Called when a new ConfigUpdate is available.
+
+<b>Signature:</b>
+
+```typescript
+next: (configUpdate: ConfigUpdate) => void;
+```

docs-devsite/remote-config.md

@@ -28,6 +28,7 @@ The Firebase Remote Config Web SDK. This SDK does not work in a Node.js environm
 |  [getNumber(remoteConfig, key)](./remote-config.md#getnumber_476c09f) | Gets the value for the given key as a number.<!-- -->Convenience method for calling <code>remoteConfig.getValue(key).asNumber()</code>. |
 |  [getString(remoteConfig, key)](./remote-config.md#getstring_476c09f) | Gets the value for the given key as a string. Convenience method for calling <code>remoteConfig.getValue(key).asString()</code>. |
 |  [getValue(remoteConfig, key)](./remote-config.md#getvalue_476c09f) | Gets the [Value](./remote-config.value.md#value_interface) for the given key. |
+|  [onConfigUpdate(remoteConfig, observer)](./remote-config.md#onconfigupdate_8b13b26) | Starts listening for real-time config updates from the Remote Config backend and automatically fetches updates from the RC backend when they are available.<p>If a connection to the Remote Config backend is not already open, calling this method will open it. Multiple listeners can be added by calling this method again, but subsequent calls re-use the same connection to the backend. |
 |  [setCustomSignals(remoteConfig, customSignals)](./remote-config.md#setcustomsignals_aeeb95e) | Sets the custom signals for the app instance. |
 |  [setLogLevel(remoteConfig, logLevel)](./remote-config.md#setloglevel_039a45b) | Defines the log level to use. |
 |  <b>function()</b> |
@@ -37,6 +38,8 @@ The Firebase Remote Config Web SDK. This SDK does not work in a Node.js environm
 
 |  Interface | Description |
 |  --- | --- |
+|  [ConfigUpdate](./remote-config.configupdate.md#configupdate_interface) | Contains information about which keys have been updated. |
+|  [ConfigUpdateObserver](./remote-config.configupdateobserver.md#configupdateobserver_interface) | Observer interface for receiving real-time Remote Config update notifications.<!-- -->NOTE: Although an <code>complete</code> callback can be provided, it will never be called because the ConfigUpdate stream is never-ending. |
 |  [CustomSignals](./remote-config.customsignals.md#customsignals_interface) | Defines the type for representing custom signals and their values.<p>The values in CustomSignals must be one of the following types:<ul> <li><code>string</code> <li><code>number</code> <li><code>null</code> </ul> |
 |  [FetchResponse](./remote-config.fetchresponse.md#fetchresponse_interface) | Defines a successful response (200 or 304).<p>Modeled after the native <code>Response</code> interface, but simplified for Remote Config's use case. |
 |  [FirebaseRemoteConfigObject](./remote-config.firebaseremoteconfigobject.md#firebaseremoteconfigobject_interface) | Defines a self-descriptive reference for config key-value pairs. |
@@ -51,6 +54,7 @@ The Firebase Remote Config Web SDK. This SDK does not work in a Node.js environm
 |  --- | --- |
 |  [FetchStatus](./remote-config.md#fetchstatus) | Summarizes the outcome of the last attempt to fetch config from the Firebase Remote Config server.<ul> <li>"no-fetch-yet" indicates the [RemoteConfig](./remote-config.remoteconfig.md#remoteconfig_interface) instance has not yet attempted to fetch config, or that SDK initialization is incomplete.</li> <li>"success" indicates the last attempt succeeded.</li> <li>"failure" indicates the last attempt failed.</li> <li>"throttle" indicates the last attempt was rate-limited.</li> </ul> |
 |  [LogLevel](./remote-config.md#loglevel) | Defines levels of Remote Config logging. |
+|  [Unsubscribe](./remote-config.md#unsubscribe) | A function that unsubscribes from a real-time event stream. |
 |  [ValueSource](./remote-config.md#valuesource) | Indicates the source of a value.<ul> <li>"static" indicates the value was defined by a static constant.</li> <li>"default" indicates the value was defined by default config.</li> <li>"remote" indicates the value was defined by fetched config.</li> </ul> |
 
 ## function(app, ...)
@@ -282,6 +286,31 @@ export declare function getValue(remoteConfig: RemoteConfig, key: string): Value
 
 The value for the given key.
 
+### onConfigUpdate(remoteConfig, observer) {:#onconfigupdate_8b13b26}
+
+Starts listening for real-time config updates from the Remote Config backend and automatically fetches updates from the RC backend when they are available.
+
+<p>If a connection to the Remote Config backend is not already open, calling this method will open it. Multiple listeners can be added by calling this method again, but subsequent calls re-use the same connection to the backend.
+
+<b>Signature:</b>
+
+```typescript
+export declare function onConfigUpdate(remoteConfig: RemoteConfig, observer: ConfigUpdateObserver): Promise<Unsubscribe>;
+```
+
+#### Parameters
+
+|  Parameter | Type | Description |
+|  --- | --- | --- |
+|  remoteConfig | [RemoteConfig](./remote-config.remoteconfig.md#remoteconfig_interface) | The [RemoteConfig](./remote-config.remoteconfig.md#remoteconfig_interface) instance. |
+|  observer | [ConfigUpdateObserver](./remote-config.configupdateobserver.md#configupdateobserver_interface) | The [ConfigUpdateObserver](./remote-config.configupdateobserver.md#configupdateobserver_interface) to be notified of config updates. |
+
+<b>Returns:</b>
+
+Promise&lt;[Unsubscribe](./remote-config.md#unsubscribe)<!-- -->&gt;
+
+An [Unsubscribe](./remote-config.md#unsubscribe) function to remove the listener.
+
 ### setCustomSignals(remoteConfig, customSignals) {:#setcustomsignals_aeeb95e}
 
 Sets the custom signals for the app instance.
@@ -365,6 +394,16 @@ Defines levels of Remote Config logging.
 export type LogLevel = 'debug' | 'error' | 'silent';
 ```
 
+## Unsubscribe
+
+A function that unsubscribes from a real-time event stream.
+
+<b>Signature:</b>
+
+```typescript
+export type Unsubscribe = () => void;
+```
+
 ## ValueSource
 
 Indicates the source of a value.

packages/remote-config/package.json

@@ -44,6 +44,7 @@
     "@firebase/logger": "0.5.0",
     "@firebase/util": "1.13.0",
     "@firebase/component": "0.7.0",
+    "date-fns": "4.1.0",
     "tslib": "^2.1.0"
   },
   "license": "Apache-2.0",

packages/remote-config/src/api.ts

@@ -22,7 +22,9 @@ import {
   LogLevel as RemoteConfigLogLevel,
   RemoteConfig,
   Value,
-  RemoteConfigOptions
+  RemoteConfigOptions,
+  ConfigUpdateObserver,
+  Unsubscribe
 } from './public_types';
 import { RemoteConfigAbortSignal } from './client/remote_config_fetch_client';
 import {
@@ -351,3 +353,29 @@ export async function setCustomSignals(
     );
   }
 }
+
+// TODO: Add public document for the Remote Config Realtime API guide on the Web Platform.
+/**
+ * Starts listening for real-time config updates from the Remote Config backend and automatically
+ * fetches updates from the RC backend when they are available.
+ *
+ * <p>If a connection to the Remote Config backend is not already open, calling this method will
+ * open it. Multiple listeners can be added by calling this method again, but subsequent calls
+ * re-use the same connection to the backend.
+ *
+ * @param remoteConfig - The {@link RemoteConfig} instance.
+ * @param observer - The {@link ConfigUpdateObserver} to be notified of config updates.
+ * @returns An {@link Unsubscribe} function to remove the listener.
+ *
+ * @public
+ */
+export async function onConfigUpdate(
+  remoteConfig: RemoteConfig,
+  observer: ConfigUpdateObserver
+): Promise<Unsubscribe> {
+  const rc = getModularInstance(remoteConfig) as RemoteConfigImpl;
+  await rc._realtimeHandler.addObserver(observer);
+  return () => {
+    rc._realtimeHandler.removeObserver(observer);
+  };
+}