feat: implement usage attribution (#844)

* feat: add internalUsageAttributionIds support (#1234)

- Extend MapOptions type to include internalUsageAttributionIds
- Implement default and custom attribution ID handling in APIProvider and GoogleMap components
- Add tests for internalUsageAttributionIds behavior
- Update TypeScript configurations to include custom type definition

* docs: add docs for usage attribution features

* chore: add reference to type augmentations

* fix: add version number to default attribution id

* chore: fix tsconfig typeRoots and includes

Author: usefulthink

docs/api-reference/components/api-provider.md

@@ -118,6 +118,19 @@ this to a generic value unique to this library (`GMP_VISGL_react`). You may
 opt out at any time by setting this prop to an empty string.
 Read more in the [documentation][gmp-solutions-usage].
 
+#### `disableUsageAttribution`: boolean
+
+To help Google understand which libraries and samples are helpful to
+developers, usage attribution IDs are sent with map requests by default.
+Set this prop to `true` to opt out of sending the usage attribution ID for
+this library.
+
+Individual maps can still specify custom attribution IDs via the
+`internalUsageAttributionIds` prop on the `<Map>` component, which will be
+used even when this option is enabled.
+
+Read more in the [documentation][gmp-usage-attribution].
+
 ### Events
 
 #### `onLoad`: () => void {#onLoad}
@@ -165,6 +178,7 @@ The following hooks are built to work with the `APIProvider` Component:
 [gmp-region]: https://developers.google.com/maps/documentation/javascript/localization#Region
 [gmp-lang]: https://developers.google.com/maps/documentation/javascript/localization
 [gmp-solutions-usage]: https://developers.google.com/maps/reporting-and-monitoring/reporting#solutions-usage
+[gmp-usage-attribution]: https://developers.google.com/maps/documentation/javascript/reference/map#MapOptions.internalUsageAttributionIds
 [api-provider-src]: https://github.com/visgl/react-google-maps/blob/main/src/components/api-provider.tsx
 [rgm-new-issue]: https://github.com/visgl/react-google-maps/issues/new/choose
 [gmp-channel-usage]: https://developers.google.com/maps/reporting-and-monitoring/reporting#usage-tracking-per-channel

docs/api-reference/components/map.md

@@ -201,6 +201,18 @@ this component will reuse map instances created with the same `mapId`,
 
 See also the section [Map Instance Caching](#map-instance-caching) above.
 
+#### `internalUsageAttributionIds`: string[]
+
+Specify custom usage attribution IDs for this map. These IDs help Google
+understand which libraries and samples are being used. When specified, the
+custom IDs are appended to a default attribution ID from the
+`APIProvider` context.
+
+If the `APIProvider` has `disableUsageAttribution` set to `true`, only the
+custom IDs specified here will be used.
+
+Read more in the [documentation][gmp-usage-attribution].
+
 ### Camera Control
 
 #### `center`: [google.maps.LatLngLiteral][gmp-ll]
@@ -368,6 +380,7 @@ to get access to the `google.maps.Map` object rendered in the `<Map>` component.
 [gmp-mapid]: https://developers.google.com/maps/documentation/get-map-id
 [gmp-map-styling]: https://developers.google.com/maps/documentation/javascript/cloud-customization
 [gmp-rendering-type]: https://developers.google.com/maps/documentation/javascript/reference/map#RenderingType
+[gmp-usage-attribution]: https://developers.google.com/maps/documentation/javascript/reference/map#MapOptions.internalUsageAttributionIds
 [api-provider]: ./api-provider.md
 [get-max-tilt]: https://github.com/visgl/react-google-maps/blob/4319bd3b68c40b9aa9b0ce7f377b52d20e824849/src/libraries/limit-tilt-range.ts#L4-L19
 [map-source]: https://github.com/visgl/react-google-maps/tree/main/src/components/map

package-lock.json

@@ -68,6 +68,7 @@
     "@googlemaps/jest-mocks": "^2.18.0",
     "@rollup/plugin-commonjs": "^28.0.8",
     "@rollup/plugin-node-resolve": "^16.0.3",
+    "@rollup/plugin-replace": "^6.0.2",
     "@rollup/plugin-typescript": "^12.1.4",
     "@testing-library/jest-dom": "^6.0.1",
     "@testing-library/react": "^16.0.0",

package.json

@@ -1,8 +1,12 @@
+import {readFileSync} from 'node:fs';
+import replace from '@rollup/plugin-replace';
 import typescript from '@rollup/plugin-typescript';
 import resolve from '@rollup/plugin-node-resolve';
 import commonjs from '@rollup/plugin-commonjs';
 import dts from 'rollup-plugin-dts';
 
+const {version: VERSION} = JSON.parse(readFileSync('./package.json', 'utf-8'));
+
 const external = ['react', 'react-dom', 'react/jsx-runtime', 'fast-deep-equal'];
 
 const plugins = [
@@ -12,6 +16,13 @@ const plugins = [
     tsconfig: './tsconfig.build.json',
     declaration: false,
     declarationDir: undefined
+  }),
+  replace({
+    preventAssignment: true,
+    include: ['src/version.ts'],
+    values: {
+      __PACKAGE_VERSION__: VERSION
+    }
   })
 ];
 

rollup.config.mjs

@@ -6,6 +6,7 @@ import '@testing-library/jest-dom';
 // FIXME: this should no longer be needed with the next version of @googlemaps/jest-mocks
 import {importLibraryMock} from '../../libraries/__mocks__/lib/import-library-mock';
 
+import {VERSION} from '../../version';
 import {
   APIProvider,
   APIProviderContext,
@@ -195,3 +196,33 @@ test('calls onError when loading the Google Maps JavaScript API fails', async ()
 
   expect(onErrorMock).toHaveBeenCalled();
 });
+
+describe('internalUsageAttributionIds', () => {
+  test('provides default attribution IDs in context', () => {
+    render(
+      <APIProvider apiKey={'apikey'}>
+        <ContextSpyComponent />
+      </APIProvider>
+    );
+
+    const contextSpy = ContextSpyComponent.spy;
+    const actualContext: APIProviderContextValue = contextSpy.mock.lastCall[0];
+
+    expect(actualContext.internalUsageAttributionIds).toEqual([
+      `gmp_visgl_reactgooglemaps_v${VERSION}`
+    ]);
+  });
+
+  test('sets internalUsageAttributionIds to null when disableUsageAttribution is true', () => {
+    render(
+      <APIProvider apiKey={'apikey'} disableUsageAttribution>
+        <ContextSpyComponent />
+      </APIProvider>
+    );
+
+    const contextSpy = ContextSpyComponent.spy;
+    const actualContext: APIProviderContextValue = contextSpy.mock.lastCall[0];
+
+    expect(actualContext.internalUsageAttributionIds).toBeNull();
+  });
+});

src/components/__tests__/api-provider.test.tsx

@@ -26,7 +26,8 @@ beforeEach(() => {
     mapInstances: {},
     addMapInstance: jest.fn(),
     removeMapInstance: jest.fn(),
-    clearMapInstances: jest.fn()
+    clearMapInstances: jest.fn(),
+    internalUsageAttributionIds: null
   };
 
   wrapper = ({children}) => (
@@ -113,7 +114,8 @@ describe('creating and updating map instance', () => {
     expect(actualOptions).toStrictEqual({
       center: {lat: 53.55, lng: 10.05},
       zoom: 12,
-      mapId: 'mymapid'
+      mapId: 'mymapid',
+      internalUsageAttributionIds: null
     });
 
     // should register the map-instance in the context
@@ -277,3 +279,70 @@ describe('camera configuration', () => {
 describe('map events and event-props', () => {
   test.todo('events dispatched by the map are received via event-props');
 });
+
+describe('internalUsageAttributionIds', () => {
+  test('uses default attribution IDs from context', () => {
+    mockContextValue.internalUsageAttributionIds = [
+      'GMP_LIB_VISGL_REACT_GOOGLE_MAPS'
+    ];
+
+    render(<GoogleMap zoom={8} center={{lat: 53.55, lng: 10.05}} />, {wrapper});
+
+    const [, options] = createMapSpy.mock.lastCall!;
+    expect(options).toMatchObject({
+      internalUsageAttributionIds: ['GMP_LIB_VISGL_REACT_GOOGLE_MAPS']
+    });
+  });
+
+  test('uses null from context when disableUsageAttribution is set', () => {
+    mockContextValue.internalUsageAttributionIds = null;
+
+    render(<GoogleMap zoom={8} center={{lat: 53.55, lng: 10.05}} />, {wrapper});
+
+    const [, options] = createMapSpy.mock.lastCall!;
+    expect(options).toBeDefined();
+    expect(options?.internalUsageAttributionIds).toBeNull();
+  });
+
+  test('appends custom attribution IDs to default IDs', () => {
+    mockContextValue.internalUsageAttributionIds = [
+      'GMP_LIB_VISGL_REACT_GOOGLE_MAPS'
+    ];
+
+    render(
+      <GoogleMap
+        zoom={8}
+        center={{lat: 53.55, lng: 10.05}}
+        internalUsageAttributionIds={['CUSTOM_ID_1', 'CUSTOM_ID_2']}
+      />,
+      {wrapper}
+    );
+
+    const [, options] = createMapSpy.mock.lastCall!;
+    expect(options).toMatchObject({
+      internalUsageAttributionIds: [
+        'GMP_LIB_VISGL_REACT_GOOGLE_MAPS',
+        'CUSTOM_ID_1',
+        'CUSTOM_ID_2'
+      ]
+    });
+  });
+
+  test('uses only custom IDs when context is disabled', () => {
+    mockContextValue.internalUsageAttributionIds = null;
+
+    render(
+      <GoogleMap
+        zoom={8}
+        center={{lat: 53.55, lng: 10.05}}
+        internalUsageAttributionIds={['CUSTOM_ID_1', 'CUSTOM_ID_2']}
+      />,
+      {wrapper}
+    );
+
+    const [, options] = createMapSpy.mock.lastCall!;
+    expect(options).toMatchObject({
+      internalUsageAttributionIds: ['CUSTOM_ID_1', 'CUSTOM_ID_2']
+    });
+  });
+});