Add setSdkInfo for SDK wrappers to self-identify

GitOrigin-RevId: 5f990bd3a106064efbdf2e73fa3dad5d5b426552

Author: mourner

src/index.esm.ts

@@ -164,6 +164,7 @@ export {default as MercatorCoordinate} from './geo/mercator_coordinate';
 export {Evented} from './util/evented';
 export {FreeCameraOptions} from './ui/free_camera';
 export {setRTLTextPlugin, getRTLTextPluginStatus} from './source/rtl_text_plugin';
+export {setSdkInfo} from './util/mapbox';
 export {addTileProvider} from './source/tile_provider';
 export {prewarm, clearPrewarmedResources} from './util/worker_pool_factory';
 export {setWorkerUrl} from './util/worker_class';

src/index.ts

@@ -17,6 +17,7 @@ import MercatorCoordinate from './geo/mercator_coordinate';
 import {Evented} from './util/evented';
 import config, {setAccessToken, setBaseApiUrl, setMaxParallelImageRequests, getDracoUrl, setDracoUrl, getMeshoptUrl, setMeshoptUrl, getBuildingGenUrl, setBuildingGenUrl} from './util/config';
 import {setRTLTextPlugin, getRTLTextPluginStatus} from './source/rtl_text_plugin';
+import {setSdkInfo} from './util/mapbox';
 import {addTileProvider} from './source/tile_provider';
 import {getWorkerCount, setWorkerCount} from './util/worker_pool';
 import WorkerClass from './util/worker_class';
@@ -84,6 +85,7 @@ const exported = {
     supported,
     setRTLTextPlugin,
     getRTLTextPluginStatus,
+    setSdkInfo,
     addTileProvider,
     Map,
     NavigationControl,

src/util/mapbox.ts

@@ -321,6 +321,28 @@ function isTelemetryEnabled(customAccessToken?: string | null): boolean {
     return true;
 }
 
+let sdkInfo: string | undefined;
+
+const SDK_INFO_RE = /^[\w.+-]+(\/[\w.+-]+)?$/;
+
+const EVENT_SCHEMA_VERSION = '2.2';
+
+/**
+ * Internal API used by Mapbox wrapper SDKs (e.g. the Flutter or React Native bridges) to
+ * self-identify in telemetry. Not part of the public API and subject to change. Pass a
+ * `Name/version` string (e.g. `'FlutterPlugin/3.0.0'`); call once at startup before any maps
+ * are created, as events from earlier maps won't carry it.
+ *
+ * @private
+ */
+export function setSdkInfo(info: string) {
+    if (typeof info !== 'string' || info.length > 64 || !SDK_INFO_RE.test(info)) {
+        warnOnce(`Invalid SDK info "${info}"; expected a "Name/version" string. Ignoring.`);
+        return;
+    }
+    sdkInfo = info;
+}
+
 type TelemetryEventType = 'appUserTurnstile' | 'map.load' | 'map.auth' | 'gljs.performance' | 'style.load' | 'metrics';
 
 export class TelemetryEvent {
@@ -550,14 +572,17 @@ export class MapLoadEvent extends TelemetryEvent {
             this.refreshUUID();
         }
 
-        const additionalPayload = {
+        const additionalPayload: Record<string, unknown> = {
+            version: EVENT_SCHEMA_VERSION,
             sdkIdentifier: 'mapbox-gl-js',
             sdkVersion,
             skuId: SKU_ID,
             skuToken: this.skuToken,
             userId: this.anonId
         };
 
+        if (sdkInfo) additionalPayload.sdkInfo = sdkInfo;
+
         // eslint-disable-next-line @typescript-eslint/no-unsafe-argument
         this.postEvent(timestamp, additionalPayload, (err) => {
             if (err) {
@@ -847,14 +872,17 @@ export class TurnstileEvent extends TelemetryEvent {
             return;
         }
 
-        const additionalPayload = {
+        const additionalPayload: Record<string, unknown> = {
+            version: EVENT_SCHEMA_VERSION,
             sdkIdentifier: 'mapbox-gl-js',
             sdkVersion,
             skuId: SKU_ID,
             "enabled.telemetry": false,
             userId: this.anonId
         };
 
+        if (sdkInfo) additionalPayload.sdkInfo = sdkInfo;
+
         // eslint-disable-next-line @typescript-eslint/no-unsafe-argument
         this.postEvent(nextUpdate, additionalPayload, (err) => {
             if (!err) {

test/unit/util/mapbox.test.ts

@@ -778,6 +778,8 @@ describe("mapbox", () => {
             // eslint-disable-next-line @typescript-eslint/no-unsafe-member-access
             expect(mapLoadEvent["enabled.telemetry"]).toEqual(false);
             // eslint-disable-next-line @typescript-eslint/no-unsafe-member-access
+            expect(mapLoadEvent.version).toEqual('2.2');
+            // eslint-disable-next-line @typescript-eslint/no-unsafe-member-access
             expect(!!mapLoadEvent.userId).toBeTruthy();
             // eslint-disable-next-line @typescript-eslint/no-unsafe-member-access
             expect(!!mapLoadEvent.created).toBeTruthy();
@@ -1206,6 +1208,34 @@ describe("mapbox", () => {
             expect(!!mapLoadEvent.userId).toBeTruthy();
             // eslint-disable-next-line @typescript-eslint/no-unsafe-member-access
             expect(!!mapLoadEvent.created).toBeTruthy();
+            // eslint-disable-next-line @typescript-eslint/no-unsafe-member-access
+            expect(mapLoadEvent.version).toEqual('2.2');
+            // eslint-disable-next-line @typescript-eslint/no-unsafe-member-access
+            expect(mapLoadEvent.sdkInfo).toBeUndefined();
+        });
+
+        test('setSdkInfo ignores invalid values', async () => {
+            mapbox.setSdkInfo('not a valid value!');
+            // eslint-disable-next-line @typescript-eslint/no-unsafe-call, @typescript-eslint/no-unsafe-member-access
+            event.postMapLoadEvent(1, skuToken);
+            // eslint-disable-next-line @typescript-eslint/no-unsafe-assignment, @typescript-eslint/no-unsafe-member-access
+            const reqBody = await window.server.requests[0].requestBody;
+            // eslint-disable-next-line @typescript-eslint/no-unsafe-assignment, @typescript-eslint/no-unsafe-argument, @typescript-eslint/no-unsafe-call, @typescript-eslint/no-unsafe-member-access
+            const mapLoadEvent = JSON.parse(reqBody.slice(1, reqBody.length - 1));
+            // eslint-disable-next-line @typescript-eslint/no-unsafe-member-access
+            expect(mapLoadEvent.sdkInfo).toBeUndefined();
+        });
+
+        test('includes sdkInfo when set via setSdkInfo', async () => {
+            mapbox.setSdkInfo('FlutterPlugin/3.0.0-beta.1');
+            // eslint-disable-next-line @typescript-eslint/no-unsafe-call, @typescript-eslint/no-unsafe-member-access
+            event.postMapLoadEvent(1, skuToken);
+            // eslint-disable-next-line @typescript-eslint/no-unsafe-assignment, @typescript-eslint/no-unsafe-member-access
+            const reqBody = await window.server.requests[0].requestBody;
+            // eslint-disable-next-line @typescript-eslint/no-unsafe-assignment, @typescript-eslint/no-unsafe-argument, @typescript-eslint/no-unsafe-call, @typescript-eslint/no-unsafe-member-access
+            const mapLoadEvent = JSON.parse(reqBody.slice(1, reqBody.length - 1));
+            // eslint-disable-next-line @typescript-eslint/no-unsafe-member-access
+            expect(mapLoadEvent.sdkInfo).toEqual('FlutterPlugin/3.0.0-beta.1');
         });
 
         test('does not POST when mapboxgl.ACCESS_TOKEN is not set', () => {