feat: Process experiment metadata in RC fetch response

Author: Athira M

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

@@ -28,12 +28,29 @@ export function fetchConfig(remoteConfig: RemoteConfig): Promise<void>;
 export interface FetchResponse {
     config?: FirebaseRemoteConfigObject;
     eTag?: string;
+    experiments?: FirebaseExperimentDescription[];
     status: number;
 }
 
 // @public
 export type FetchStatus = 'no-fetch-yet' | 'success' | 'failure' | 'throttle';
 
+// @public
+export interface FirebaseExperimentDescription {
+    // (undocumented)
+    affectedParameterKeys?: string[];
+    // (undocumented)
+    experimentId: string;
+    // (undocumented)
+    experimentStartTime: string;
+    // (undocumented)
+    timeToLiveMillis: string;
+    // (undocumented)
+    triggerTimeoutMillis: string;
+    // (undocumented)
+    variantId: string;
+}
+
 // @public
 export interface FirebaseRemoteConfigObject {
     // (undocumented)

packages/remote-config/src/api.ts

@@ -97,6 +97,7 @@ export async function activate(remoteConfig: RemoteConfig): Promise<boolean> {
   if (
     !lastSuccessfulFetchResponse ||
     !lastSuccessfulFetchResponse.config ||
+    !lastSuccessfulFetchResponse.experiments ||
     !lastSuccessfulFetchResponse.eTag ||
     lastSuccessfulFetchResponse.eTag === activeConfigEtag
   ) {

packages/remote-config/src/client/rest_client.ts

@@ -18,7 +18,8 @@
 import {
   CustomSignals,
   FetchResponse,
-  FirebaseRemoteConfigObject
+  FirebaseRemoteConfigObject,
+  FirebaseExperimentDescription
 } from '../public_types';
 import {
   RemoteConfigFetchClient,
@@ -140,6 +141,7 @@ export class RestClient implements RemoteConfigFetchClient {
 
     let config: FirebaseRemoteConfigObject | undefined;
     let state: string | undefined;
+    let experiments: FirebaseExperimentDescription[] | undefined;
 
     // JSON parsing throws SyntaxError if the response body isn't a JSON string.
     // Requesting application/json and checking for a 200 ensures there's JSON data.
@@ -154,6 +156,7 @@ export class RestClient implements RemoteConfigFetchClient {
       }
       config = responseBody['entries'];
       state = responseBody['state'];
+      experiments = responseBody['experimentDescriptions'];
     }
 
     // Normalizes based on legacy state.
@@ -164,6 +167,7 @@ export class RestClient implements RemoteConfigFetchClient {
     } else if (state === 'NO_TEMPLATE' || state === 'EMPTY_CONFIG') {
       // These cases can be fixed remotely, so normalize to safe value.
       config = {};
+      experiments = [];
     }
 
     // Normalize to exception-based control flow for non-success cases.
@@ -176,6 +180,6 @@ export class RestClient implements RemoteConfigFetchClient {
       });
     }
 
-    return { status, eTag: responseEtag, config };
+    return { status, eTag: responseEtag, config, experiments };
   }
 }

packages/remote-config/src/public_types.ts

@@ -57,6 +57,32 @@ export interface FirebaseRemoteConfigObject {
   [key: string]: string;
 }
 
+/**
+ * Defines experiment and variant attached to a config parameter.
+ */
+export interface FirebaseExperimentDescription {
+  // A string of max length 22 characters and of format: _exp_<experiment_id>
+  experimentId: string;
+
+  // The variant of the experiment assigned to the app instance.
+  variantId: string;
+
+  // When the experiment was started.
+  experimentStartTime: string;
+
+  // How long the experiment can remain in STANDBY state. Valid range from 1 ms
+  // to 6 months.
+  triggerTimeoutMillis: string;
+
+  // How long the experiment can remain in ON state. Valid range from 1 ms to 6
+  // months.
+  timeToLiveMillis: string;
+
+  // A repeated of Remote Config parameter keys that this experiment is
+  // affecting the value of.
+  affectedParameterKeys?: string[];
+}
+
 /**
  * Defines a successful response (200 or 304).
  *
@@ -90,8 +116,12 @@ export interface FetchResponse {
    */
   config?: FirebaseRemoteConfigObject;
 
-  // Note: we're not extracting experiment metadata until
-  // ABT and Analytics have Web SDKs.
+  /**
+   * A/B Test and Rollout experiment metadata.
+   * 
+   * <p>Only defined for 200 responses.
+   */
+  experiments?: FirebaseExperimentDescription[];
 }
 
 /**

packages/remote-config/test/api.test.ts

@@ -57,7 +57,14 @@ describe('Remote Config API', () => {
   const STUB_FETCH_RESPONSE: FetchResponse = {
     status: 200,
     eTag: 'asdf',
-    config: { 'foobar': 'hello world' }
+    config: { 'foobar': 'hello world' },
+    experiments: [{
+      experimentId: "_exp_1",
+      variantId : "1",
+      experimentStartTime : "2025-04-06T14:13:57.597Z",
+      triggerTimeoutMillis : "15552000000",
+      timeToLiveMillis : "15552000000"
+    }]
   };
   let fetchStub: sinon.SinonStub;
 
@@ -94,6 +101,7 @@ describe('Remote Config API', () => {
         json: () =>
           Promise.resolve({
             entries: response.config,
+            experimentDescriptions: response.experiments,
             state: 'OK'
           })
       } as Response)

packages/remote-config/test/client/rest_client.test.ts

@@ -74,7 +74,14 @@ describe('RestClient', () => {
         status: 200,
         eTag: 'etag',
         state: 'UPDATE',
-        entries: { color: 'sparkling' }
+        entries: { color: 'sparkling' },
+        experimentDescriptions: [{
+          experimentId: "_exp_1",
+          variantId : "1",
+          experimentStartTime : "2025-04-06T14:13:57.597Z",
+          triggerTimeoutMillis : "15552000000",
+          timeToLiveMillis : "15552000000"
+        }]
       };
 
       fetchStub.returns(
@@ -85,7 +92,8 @@ describe('RestClient', () => {
           json: () =>
             Promise.resolve({
               entries: expectedResponse.entries,
-              state: expectedResponse.state
+              state: expectedResponse.state,
+              experimentDescriptions: expectedResponse.experimentDescriptions
             })
         } as Response)
       );
@@ -95,7 +103,8 @@ describe('RestClient', () => {
       expect(response).to.deep.eq({
         status: expectedResponse.status,
         eTag: expectedResponse.eTag,
-        config: expectedResponse.entries
+        config: expectedResponse.entries,
+        experiments: expectedResponse.experimentDescriptions
       });
     });
 
@@ -184,7 +193,8 @@ describe('RestClient', () => {
       expect(response).to.deep.eq({
         status: 304,
         eTag: 'response-etag',
-        config: undefined
+        config: undefined,
+        experiments: undefined
       });
     });
 
@@ -222,7 +232,8 @@ describe('RestClient', () => {
       expect(response).to.deep.eq({
         status: 304,
         eTag: 'etag',
-        config: undefined
+        config: undefined,
+        experiments: undefined
       });
     });
 
@@ -239,7 +250,8 @@ describe('RestClient', () => {
         await expect(client.fetch(DEFAULT_REQUEST)).to.eventually.be.deep.eq({
           status: 200,
           eTag: 'etag',
-          config: {}
+          config: {},
+          experiments: []
         });
       }
     });

packages/remote-config/test/remote_config.test.ts

@@ -380,6 +380,13 @@ describe('RemoteConfig', () => {
     const ETAG = 'etag';
     const CONFIG = { key: 'val' };
     const NEW_ETAG = 'new_etag';
+    const EXPERIMENTS = [{
+      "experimentId" : "_exp_1",
+      "variantId" : "1",
+      "experimentStartTime" : "2025-04-06T14:13:57.597Z",
+      "triggerTimeoutMillis" : "15552000000",
+      "timeToLiveMillis" : "15552000000"   
+    }];
 
     let getLastSuccessfulFetchResponseStub: sinon.SinonStub;
     let getActiveConfigEtagStub: sinon.SinonStub;
@@ -425,7 +432,7 @@ describe('RemoteConfig', () => {
 
     it('activates if fetched and active etags are different', async () => {
       getLastSuccessfulFetchResponseStub.returns(
-        Promise.resolve({ config: CONFIG, eTag: NEW_ETAG })
+        Promise.resolve({ config: CONFIG, experiments: EXPERIMENTS, eTag: NEW_ETAG })
       );
       getActiveConfigEtagStub.returns(Promise.resolve(ETAG));
 
@@ -438,7 +445,7 @@ describe('RemoteConfig', () => {
 
     it('activates if fetched is defined but active config is not', async () => {
       getLastSuccessfulFetchResponseStub.returns(
-        Promise.resolve({ config: CONFIG, eTag: NEW_ETAG })
+        Promise.resolve({ config: CONFIG, experiments: EXPERIMENTS, eTag: NEW_ETAG })
       );
       getActiveConfigEtagStub.returns(Promise.resolve());