feat(ai): send X-Firebase-AppVersion when data collection enabled (#9173)

Author: russellwheatley

docs/app/utils.mdx

@@ -45,6 +45,24 @@ async function bootstrap() {
 }
 ```
 
+# App Version
+
+`appVersion` returns the host app's marketing version string: Android `versionName` or iOS
+`CFBundleShortVersionString`. Use it when you need the installed app version without pulling in a
+separate package.
+
+> Be aware, `appVersion` is available on Android and iOS only. On web and other non-native platforms
+> it is `undefined` (including when the native value is empty).
+
+```js
+import { utils } from '@react-native-firebase/app';
+
+const version = utils().appVersion;
+if (version) {
+  console.log('App version:', version);
+}
+```
+
 # Android - Checking Play Services
 
 It is useful to know if the Android device has play services available, and what to do in response to certain use cases:

jest.setup.ts

@@ -88,6 +88,7 @@ jest.doMock('react-native', () => {
         NativeRNFBTurboUtils: {
           getConstants: () => ({
             isRunningInTestLab: false,
+            appVersion: '1.0.0',
             MAIN_BUNDLE: '/',
             CACHES_DIRECTORY: '/cache',
             DOCUMENT_DIRECTORY: '/documents',
@@ -97,6 +98,7 @@ jest.doMock('react-native', () => {
             MOVIES_DIRECTORY: '/movies',
           }),
           isRunningInTestLab: false,
+          appVersion: '1.0.0',
           MAIN_BUNDLE: '/',
           CACHES_DIRECTORY: '/cache',
           DOCUMENT_DIRECTORY: '/documents',

packages/ai/__tests__/request.test.ts

@@ -15,7 +15,15 @@
  * limitations under the License.
  */
 import { describe, expect, it, jest, afterEach } from '@jest/globals';
-import { RequestUrl, Task, getHeaders, makeRequest } from '../lib/requests/request';
+import {
+  RequestUrl,
+  Task,
+  TemplateRequestUrl,
+  ServerPromptTemplateTask,
+  getHeaders,
+  getTemplateHeaders,
+  makeRequest,
+} from '../lib/requests/request';
 import { ApiSettings } from '../lib/types/internal';
 import { DEFAULT_API_VERSION } from '../lib/constants';
 import { AIErrorCode } from '../lib/types';
@@ -282,6 +290,174 @@ describe('request methods', () => {
       const headers = await getHeaders(fakeUrl);
       expect(headers.has('Authorization')).toBe(false);
     });
+
+    it('adds X-Firebase-Appid and X-Firebase-AppVersion when collection enabled', async () => {
+      const fakeUrl = new RequestUrl(
+        'models/model-name',
+        Task.GENERATE_CONTENT,
+        {
+          apiKey: 'key',
+          project: 'myproject',
+          appId: 'my-appid',
+          location: 'moon',
+          backend: new VertexAIBackend(),
+          automaticDataCollectionEnabled: true,
+          appVersion: '2.3.4',
+        },
+        true,
+        {},
+      );
+      const headers = await getHeaders(fakeUrl);
+      expect(headers.get('X-Firebase-Appid')).toBe('my-appid');
+      expect(headers.get('X-Firebase-AppVersion')).toBe('2.3.4');
+    });
+
+    it('omits AppId and AppVersion when collection disabled', async () => {
+      const fakeUrl = new RequestUrl(
+        'models/model-name',
+        Task.GENERATE_CONTENT,
+        {
+          apiKey: 'key',
+          project: 'myproject',
+          appId: 'my-appid',
+          location: 'moon',
+          backend: new VertexAIBackend(),
+          automaticDataCollectionEnabled: false,
+          appVersion: '2.3.4',
+        },
+        true,
+        {},
+      );
+      const headers = await getHeaders(fakeUrl);
+      expect(headers.has('X-Firebase-Appid')).toBe(false);
+      expect(headers.has('X-Firebase-AppVersion')).toBe(false);
+    });
+
+    it('adds AppId but omits AppVersion when version missing', async () => {
+      const fakeUrl = new RequestUrl(
+        'models/model-name',
+        Task.GENERATE_CONTENT,
+        {
+          apiKey: 'key',
+          project: 'myproject',
+          appId: 'my-appid',
+          location: 'moon',
+          backend: new VertexAIBackend(),
+          automaticDataCollectionEnabled: true,
+        },
+        true,
+        {},
+      );
+      const headers = await getHeaders(fakeUrl);
+      expect(headers.get('X-Firebase-Appid')).toBe('my-appid');
+      expect(headers.has('X-Firebase-AppVersion')).toBe(false);
+    });
+
+    it('omits AppVersion when version is empty string', async () => {
+      const fakeUrl = new RequestUrl(
+        'models/model-name',
+        Task.GENERATE_CONTENT,
+        {
+          apiKey: 'key',
+          project: 'myproject',
+          appId: 'my-appid',
+          location: 'moon',
+          backend: new VertexAIBackend(),
+          automaticDataCollectionEnabled: true,
+          appVersion: '',
+        },
+        true,
+        {},
+      );
+      const headers = await getHeaders(fakeUrl);
+      expect(headers.get('X-Firebase-Appid')).toBe('my-appid');
+      expect(headers.has('X-Firebase-AppVersion')).toBe(false);
+    });
+  });
+
+  describe('getTemplateHeaders', () => {
+    it('adds X-Firebase-Appid and X-Firebase-AppVersion when collection enabled', async () => {
+      const fakeUrl = new TemplateRequestUrl(
+        'template-id',
+        ServerPromptTemplateTask.TEMPLATE_GENERATE_CONTENT,
+        {
+          apiKey: 'key',
+          project: 'myproject',
+          appId: 'my-appid',
+          location: 'moon',
+          backend: new VertexAIBackend(),
+          automaticDataCollectionEnabled: true,
+          appVersion: '9.9.9',
+        },
+        false,
+        {},
+      );
+      const headers = await getTemplateHeaders(fakeUrl);
+      expect(headers.get('X-Firebase-Appid')).toBe('my-appid');
+      expect(headers.get('X-Firebase-AppVersion')).toBe('9.9.9');
+    });
+
+    it('omits AppId and AppVersion when collection disabled', async () => {
+      const fakeUrl = new TemplateRequestUrl(
+        'template-id',
+        ServerPromptTemplateTask.TEMPLATE_GENERATE_CONTENT,
+        {
+          apiKey: 'key',
+          project: 'myproject',
+          appId: 'my-appid',
+          location: 'moon',
+          backend: new VertexAIBackend(),
+          automaticDataCollectionEnabled: false,
+          appVersion: '9.9.9',
+        },
+        false,
+        {},
+      );
+      const headers = await getTemplateHeaders(fakeUrl);
+      expect(headers.has('X-Firebase-Appid')).toBe(false);
+      expect(headers.has('X-Firebase-AppVersion')).toBe(false);
+    });
+
+    it('adds AppId but omits AppVersion when version missing', async () => {
+      const fakeUrl = new TemplateRequestUrl(
+        'template-id',
+        ServerPromptTemplateTask.TEMPLATE_GENERATE_CONTENT,
+        {
+          apiKey: 'key',
+          project: 'myproject',
+          appId: 'my-appid',
+          location: 'moon',
+          backend: new VertexAIBackend(),
+          automaticDataCollectionEnabled: true,
+        },
+        false,
+        {},
+      );
+      const headers = await getTemplateHeaders(fakeUrl);
+      expect(headers.get('X-Firebase-Appid')).toBe('my-appid');
+      expect(headers.has('X-Firebase-AppVersion')).toBe(false);
+    });
+
+    it('omits AppVersion when version is empty string', async () => {
+      const fakeUrl = new TemplateRequestUrl(
+        'template-id',
+        ServerPromptTemplateTask.TEMPLATE_GENERATE_CONTENT,
+        {
+          apiKey: 'key',
+          project: 'myproject',
+          appId: 'my-appid',
+          location: 'moon',
+          backend: new VertexAIBackend(),
+          automaticDataCollectionEnabled: true,
+          appVersion: '',
+        },
+        false,
+        {},
+      );
+      const headers = await getTemplateHeaders(fakeUrl);
+      expect(headers.get('X-Firebase-Appid')).toBe('my-appid');
+      expect(headers.has('X-Firebase-AppVersion')).toBe(false);
+    });
   });
 
   describe('makeRequest', () => {

packages/ai/__tests__/utils.test.ts

@@ -15,13 +15,23 @@
  * limitations under the License.
  */
 import { describe, expect, it, jest } from '@jest/globals';
-import { type ReactNativeFirebase } from '@react-native-firebase/app';
+import { getUtils, type ReactNativeFirebase } from '@react-native-firebase/app';
 import { AI, AIErrorCode } from '../lib/public-types';
 import { AIError } from '../lib/errors';
 import { VertexAIBackend } from '../lib/backend';
 import { AIService } from '../lib/service';
 import { initApiSettings } from '../lib/models/utils';
 
+jest.mock('@react-native-firebase/app', () => {
+  const actual = jest.requireActual<typeof import('@react-native-firebase/app')>(
+    '@react-native-firebase/app',
+  );
+  return {
+    ...actual,
+    getUtils: jest.fn((...args: Parameters<typeof actual.getUtils>) => actual.getUtils(...args)),
+  };
+});
+
 const fakeAI: AI = {
   app: {
     name: 'DEFAULT',
@@ -159,4 +169,24 @@ describe('initApiSettings', function () {
       expect((e as AIError).code).toBe(AIErrorCode.NO_APP_ID);
     }
   });
+
+  it('populates appVersion from app utils when available', function () {
+    const apiSettings = initApiSettings(fakeAI);
+    expect(apiSettings.appVersion).toBe('1.0.0');
+  });
+
+  it('omits appVersion when getUtils throws', function () {
+    jest.mocked(getUtils).mockImplementationOnce(() => {
+      throw new Error('native utils unavailable');
+    });
+
+    const apiSettings = initApiSettings(fakeAI);
+    expect(apiSettings.appVersion).toBeUndefined();
+    expect(apiSettings.apiKey).toBe('key');
+    expect(apiSettings.project).toBe('my-project');
+    expect(apiSettings.appId).toBe('my-appid');
+    expect(apiSettings.location).toBe('us-central1');
+    expect(apiSettings.automaticDataCollectionEnabled).toBe(true);
+    expect(apiSettings.backend).toBe(fakeAI.backend);
+  });
 });

packages/ai/lib/models/utils.ts

@@ -16,6 +16,7 @@
  */
 import type { AppCheck } from '@react-native-firebase/app-check';
 import { getLimitedUseToken, getToken } from '@react-native-firebase/app-check';
+import { getUtils } from '@react-native-firebase/app';
 import { AIError } from '../errors';
 import { AI, AIErrorCode } from '../public-types';
 import { AIService } from '../service';
@@ -53,6 +54,16 @@ export function initApiSettings(ai: AI): ApiSettings {
     backend: ai.backend,
   };
 
+  try {
+    // Utils is single-app (hasMultiAppSupport: false); do not pass ai.app.
+    const appVersion = getUtils().appVersion;
+    if (appVersion) {
+      apiSettings.appVersion = appVersion;
+    }
+  } catch {
+    // Native utils unavailable (web / non-native) — omit appVersion.
+  }
+
   const appCheck = ai.appCheck as AppCheck;
   if (appCheck) {
     apiSettings.getAppCheckToken = () =>

packages/ai/lib/requests/request.ts

@@ -163,6 +163,9 @@ export async function getHeaders(url: RequestUrl): Promise<Headers> {
   headers.append('x-goog-api-key', url.apiSettings.apiKey);
   if (url.apiSettings.automaticDataCollectionEnabled) {
     headers.append('X-Firebase-Appid', url.apiSettings.appId);
+    if (url.apiSettings.appVersion) {
+      headers.append('X-Firebase-AppVersion', url.apiSettings.appVersion);
+    }
   }
   if (url.apiSettings.getAppCheckToken) {
     let appCheckToken;
@@ -194,6 +197,9 @@ export async function getTemplateHeaders(url: TemplateRequestUrl): Promise<Heade
   headers.append('x-goog-api-key', url.apiSettings.apiKey);
   if (url.apiSettings.automaticDataCollectionEnabled) {
     headers.append('X-Firebase-Appid', url.apiSettings.appId);
+    if (url.apiSettings.appVersion) {
+      headers.append('X-Firebase-AppVersion', url.apiSettings.appVersion);
+    }
   }
   if (url.apiSettings.getAppCheckToken) {
     let appCheckToken;

packages/ai/lib/types/internal.ts

@@ -26,6 +26,10 @@ export interface ApiSettings {
    */
   location: string;
   automaticDataCollectionEnabled?: boolean;
+  /**
+   * Host app marketing version when available (Android versionName / iOS CFBundleShortVersionString).
+   */
+  appVersion?: string;
   backend: Backend;
   getAuthToken?: () => Promise<string>;
   getAppCheckToken?: () => Promise<AppCheckTokenResult>;

packages/app/android/src/reactnative/java/io/invertase/firebase/app/generated/java/com/facebook/fbreact/specs/NativeRNFBTurboUtilsSpec.java

@@ -59,7 +59,8 @@ public NativeRNFBTurboUtilsSpec(ReactApplicationContext reactContext) {
           "EXTERNAL_DIRECTORY",
           "EXTERNAL_STORAGE_DIRECTORY",
           "FILE_TYPE_DIRECTORY",
-          "FILE_TYPE_REGULAR"
+          "FILE_TYPE_REGULAR",
+          "appVersion"
       ));
       Set<String> undeclaredConstants = new HashSet<>(constants.keySet());
       undeclaredConstants.removeAll(obligatoryFlowConstants);

packages/app/android/src/reactnative/java/io/invertase/firebase/utils/NativeRNFBTurboUtils.java

@@ -135,6 +135,16 @@ public void androidMakePlayServicesAvailable(Promise promise) {
     }
   }
 
+  private static String getAppVersionName(Context context) {
+    try {
+      return context.getPackageManager().getPackageInfo(context.getPackageName(), 0).versionName;
+    } catch (Exception error) {
+      // Optional metadata: prefer omit over crashing on null context / unexpected PM failures.
+      Log.d(TAG, "getAppVersionName", error);
+      return null;
+    }
+  }
+
   private int isGooglePlayServicesAvailable() {
     GoogleApiAvailability gapi = GoogleApiAvailability.getInstance();
     return gapi.isGooglePlayServicesAvailable(getReactApplicationContext());
@@ -166,6 +176,11 @@ protected Map<String, Object> getTypedExportedConstants() {
     constants.put("isRunningInTestLab", isRunningInTestLab());
 
     Context context = getReactApplicationContext();
+    String appVersion = getAppVersionName(context);
+    if (appVersion != null && !appVersion.isEmpty()) {
+      constants.put("appVersion", appVersion);
+    }
+
     constants.put(KEY_MAIN_BUNDLE, "");
     constants.put(KEY_LIBRARY_DIRECTORY, context.getFilesDir().getAbsolutePath());
     constants.put(KEY_TEMP_DIRECTORY, context.getCacheDir().getAbsolutePath());