feat: add solution-channel parameter (#334)

The solution channel parameter helps Google understand the types of usage of the Google Maps JavaScript API. We will by default set a value unique to this library.

Co-authored-by: Martin Schuhfuss <[email protected]>

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

@@ -103,6 +103,19 @@ when authorizing requests from the Maps JavaScript API.
 A list of [libraries][gmp-libs] to load immediately
 (libraries can also be loaded later with the `useMapsLibrary` hook).
 
+#### `solutionChannel`: string
+
+To help Google to better understand types of usage of the Google Maps 
+JavaScript API, the query parameter `solution_channel` can be set when 
+loading the API. 
+
+The `@vis.gl/react-google-maps` library will by default set 
+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].
+
+### Events
+
 #### `onLoad`: () => void {#onLoad}
 
 a callback that is called once the Maps JavaScript
@@ -142,5 +155,6 @@ The following hooks are built to work with the `APIProvider` Component:
 [gmp-libs]: https://developers.google.com/maps/documentation/javascript/libraries
 [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
 [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

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

@@ -67,6 +67,7 @@ test('passes parameters to GoogleMapsAPILoader', () => {
       version={'beta'}
       language={'en'}
       region={'us'}
+      solutionChannel={'test-channel_value'}
       authReferrerPolicy={'origin'}></APIProvider>
   );
 
@@ -76,15 +77,30 @@ test('passes parameters to GoogleMapsAPILoader', () => {
     v: 'beta',
     language: 'en',
     region: 'us',
+    solutionChannel: 'test-channel_value',
     authReferrerPolicy: 'origin'
   });
 });
 
 test('passes parameters to GoogleMapsAPILoader', () => {
+  render(<APIProvider apiKey={'apikey'} version={'version'}></APIProvider>);
+
+  const actual = apiLoadSpy.mock.lastCall[0];
+  expect(actual).toMatchObject({key: 'apikey', v: 'version'});
+});
+
+test('uses default solutionChannel', () => {
   render(<APIProvider apiKey={'apikey'}></APIProvider>);
 
   const actual = apiLoadSpy.mock.lastCall[0];
-  expect(Object.keys(actual)).toMatchObject(['key']);
+  expect(actual.solutionChannel).toBe('GMP_VISGL_react');
+});
+
+test("doesn't set solutionChannel when specified as empty string", () => {
+  render(<APIProvider apiKey={'apikey'} solutionChannel={''}></APIProvider>);
+
+  const actual = apiLoadSpy.mock.lastCall[0];
+  expect(actual).not.toHaveProperty('solutionChannel');
 });
 
 test('renders inner components', async () => {

src/components/api-provider.tsx

@@ -28,6 +28,8 @@ export interface APIProviderContextValue {
   clearMapInstances: () => void;
 }
 
+const DEFAULT_SOLUTION_CHANNEL = 'GMP_VISGL_react';
+
 export const APIProviderContext =
   React.createContext<APIProviderContextValue | null>(null);
 
@@ -65,6 +67,14 @@ export type APIProviderProps = {
    * Part of: https://developers.google.com/maps/documentation/javascript/url-params
    */
   authReferrerPolicy?: string;
+  /**
+   * To understand usage and ways to improve our solutions, Google includes the
+   * `solution_channel` query parameter in API calls to gather information about
+   * code usage. You may opt out at any time by setting this attribute to an
+   * empty string. Read more in the
+   * [documentation](https://developers.google.com/maps/reporting-and-monitoring/reporting#solutions-usage).
+   */
+  solutionChannel?: string;
   /**
    * A function that can be used to execute code after the Google Maps JavaScript API has been loaded.
    */
@@ -150,6 +160,10 @@ function useGoogleMapsApiLoader(props: APIProviderProps) {
           if (version) params.v = version;
           if (librariesString?.length > 0) params.libraries = librariesString;
 
+          if (params.solutionChannel === undefined)
+            params.solutionChannel = DEFAULT_SOLUTION_CHANNEL;
+          else if (params.solutionChannel === '') delete params.solutionChannel;
+
           await GoogleMapsApiLoader.load(params, status => setStatus(status));
 
           for (const name of ['core', 'maps', ...libraries]) {