Add implementation of getGoogleAnalyticsClientId

.changeset/silent-islands-fix.md

@@ -0,0 +1,6 @@
+---
+'@firebase/analytics': minor
+'firebase': minor
+---
+
+Add method `getGoogleAnalyticsClientId()` to retrieve an unique identifier for a web client. Users wanted to log purchase and other events from their backends using Google Analytics 4 Measurement Protocol and to have those events be connected to actions taken on the client within their Firebase web app. `getGoogleAnalyticsClientId()` will simply this event recording process.

common/api-review/analytics.api.md

@@ -133,6 +133,9 @@ export interface EventParams {
 // @public
 export function getAnalytics(app?: FirebaseApp): Analytics;
 
+// @public
+export function getGoogleAnalyticsClientId(analyticsInstance: Analytics): Promise<string>;
+
 // @public
 export interface GtagConfigParams {
     // (undocumented)

docs-devsite/analytics.md

@@ -20,6 +20,7 @@ Firebase Analytics
 |  [getAnalytics(app)](./analytics.md#getanalytics) | Returns an [Analytics](./analytics.analytics.md#analytics_interface) instance for the given app. |
 |  [initializeAnalytics(app, options)](./analytics.md#initializeanalytics) | Returns an [Analytics](./analytics.analytics.md#analytics_interface) instance for the given app. |
 |  <b>function(analyticsInstance...)</b> |
+|  [getGoogleAnalyticsClientId(analyticsInstance)](./analytics.md#getgoogleanalyticsclientid) | Retrieves a unique identifier for the web client. |
 |  [logEvent(analyticsInstance, eventName, eventParams, options)](./analytics.md#logevent) | Sends a Google Analytics event with given <code>eventParams</code>. This method automatically associates this logged event with this Firebase web app instance on this device.<!-- -->List of recommended event parameters can be found in [the GA4 reference documentation](https://developers.google.com/gtagjs/reference/ga4-events)<!-- -->. |
 |  [logEvent(analyticsInstance, eventName, eventParams, options)](./analytics.md#logevent) | Sends a Google Analytics event with given <code>eventParams</code>. This method automatically associates this logged event with this Firebase web app instance on this device.<!-- -->List of recommended event parameters can be found in [the GA4 reference documentation](https://developers.google.com/gtagjs/reference/ga4-events)<!-- -->. |
 |  [logEvent(analyticsInstance, eventName, eventParams, options)](./analytics.md#logevent) | Sends a Google Analytics event with given <code>eventParams</code>. This method automatically associates this logged event with this Firebase web app instance on this device.<!-- -->See [Track Screenviews](https://firebase.google.com/docs/analytics/screenviews)<!-- -->. |
@@ -121,6 +122,26 @@ export declare function initializeAnalytics(app: FirebaseApp, options?: Analytic
 
 [Analytics](./analytics.analytics.md#analytics_interface)
 
+## getGoogleAnalyticsClientId()
+
+Retrieves a unique identifier for the web client.
+
+<b>Signature:</b>
+
+```typescript
+export declare function getGoogleAnalyticsClientId(analyticsInstance: Analytics): Promise<string>;
+```
+
+### Parameters
+
+|  Parameter | Type | Description |
+|  --- | --- | --- |
+|  analyticsInstance | [Analytics](./analytics.analytics.md#analytics_interface) |  |
+
+<b>Returns:</b>
+
+Promise&lt;string&gt;
+
 ## logEvent()
 
 Sends a Google Analytics event with given `eventParams`<!-- -->. This method automatically associates this logged event with this Firebase web app instance on this device.

packages/analytics/src/api.ts

@@ -167,6 +167,40 @@ export function setCurrentScreen(
   ).catch(e => logger.error(e));
 }
 
+/**
+ * Retrieves a unique identifier for the web client.
+ *
+ * @public
+ *
+ * @param app - The {@link @firebase/app#FirebaseApp} to use.
+ */
+export async function getGoogleAnalyticsClientId(
+  analyticsInstance: Analytics
+): Promise<string> {
+  analyticsInstance = getModularInstance(analyticsInstance);
+  const measurementId = analyticsInstance.app.options.measurementId;
+  let clientId = '';
+  if (!measurementId) {
+    logger.error('The app has no recognizable measurement ID.');
+  } else {
+    clientId = await new Promise((resolve, reject) => {
+      wrappedGtagFunction(
+        GtagCommand.GET,
+        measurementId,
+        'client_id',
+        fieldName => {
+          if (!fieldName) {
+            reject('There was an issue retrieving the `client_id`');
+          }
+          resolve(fieldName);
+        }
+      );
+    });
+  }
+
+  return clientId;
+}
+
 /**
  * Use gtag `config` command to set `user_id`.
  *

packages/analytics/src/constants.ts

@@ -35,5 +35,6 @@ export const enum GtagCommand {
   EVENT = 'event',
   SET = 'set',
   CONFIG = 'config',
-  CONSENT = 'consent'
+  CONSENT = 'consent',
+  GET = 'get'
 }

packages/analytics/src/helpers.test.ts

@@ -263,6 +263,24 @@ describe('Gtag wrapping functions', () => {
       expect((window['dataLayer'] as DataLayer).length).to.equal(1);
     });
 
+    it('new window.gtag function does not wait when sending "get" calls', async () => {
+      wrapOrCreateGtag(
+        { [fakeAppId]: Promise.resolve(fakeMeasurementId) },
+        fakeDynamicConfigPromises,
+        {},
+        'dataLayer',
+        'gtag'
+      );
+      window['dataLayer'] = [];
+      (window['gtag'] as Gtag)(
+        GtagCommand.GET,
+        fakeMeasurementId,
+        'client_id',
+        fieldName => console.log(fieldName)
+      );
+      expect((window['dataLayer'] as DataLayer).length).to.equal(1);
+    });
+
     it('new window.gtag function waits for initialization promise when sending "config" calls', async () => {
       const initPromise1 = new Deferred<string>();
       wrapOrCreateGtag(

packages/analytics/src/helpers.ts

@@ -227,9 +227,10 @@ function wrapGtag(
    * @param gtagParams Params if event is EVENT/CONFIG.
    */
   async function gtagWrapper(
-    command: 'config' | 'set' | 'event' | 'consent',
+    command: 'config' | 'set' | 'event' | 'consent' | 'get',
     idOrNameOrParams: string | ControlParams,
-    gtagParams?: GtagConfigOrEventParams | ConsentSettings
+    gtagParams?: GtagConfigOrEventParams | ConsentSettings | string,
+    callback?: (s: string) => void
   ): Promise<void> {
     try {
       // If event, check that relevant initialization promises have completed.
@@ -255,6 +256,13 @@ function wrapGtag(
       } else if (command === GtagCommand.CONSENT) {
         // If CONFIG, second arg must be measurementId.
         gtagCore(GtagCommand.CONSENT, 'update', gtagParams as ConsentSettings);
+      } else if (command === GtagCommand.GET) {
+        gtagCore(
+          GtagCommand.GET,
+          idOrNameOrParams as string,
+          gtagParams as string,
+          callback as (fieldName: string) => void
+        );
       } else {
         // If SET, second arg must be params.
         gtagCore(GtagCommand.SET, idOrNameOrParams as CustomParams);

packages/analytics/src/types.ts

@@ -73,6 +73,12 @@ export interface Gtag {
     subCommand: 'default' | 'update',
     consentSettings: ConsentSettings
   ): void;
+  (
+    command: 'get',
+    targetId: string,
+    fieldName: string,
+    callback: (s: string) => void
+  ): void;
 }
 
 export type DataLayer = IArguments[];