Add function setConsent() to set end user consent state for web apps in Firebase Analytics

.changeset/shiny-bats-reflect.md

@@ -0,0 +1,5 @@
+---
+'@firebase/analytics': minor
+---
+
+Add function `setConsent()` to set the applicable end user "consent" state.

common/api-review/analytics.api.md

@@ -21,6 +21,17 @@ export interface AnalyticsSettings {
     config?: GtagConfigParams | EventParams;
 }
 
+// @public
+export interface ConsentSettings {
+    // (undocumented)
+    ad_storage?: ConsentStatusString;
+    // (undocumented)
+    analytics_storage?: ConsentStatusString;
+}
+
+// @public
+export type ConsentStatusString = 'granted' | 'denied';
+
 // @public
 export interface ControlParams {
     // (undocumented)
@@ -388,6 +399,9 @@ export interface Promotion {
 // @public
 export function setAnalyticsCollectionEnabled(analyticsInstance: Analytics, enabled: boolean): void;
 
+// @public
+export function setConsent(consentSettings: ConsentSettings): void;
+
 // @public @deprecated
 export function setCurrentScreen(analyticsInstance: Analytics, screenName: string, options?: AnalyticsCallOptions): void;
 

packages/analytics/src/api.ts

@@ -22,6 +22,7 @@ import {
   Analytics,
   AnalyticsCallOptions,
   AnalyticsSettings,
+  ConsentSettings,
   CustomParams,
   EventNameString,
   EventParams
@@ -35,7 +36,7 @@ import {
   getModularInstance,
   deepEqual
 } from '@firebase/util';
-import { ANALYTICS_TYPE } from './constants';
+import { ANALYTICS_TYPE, GtagCommand } from './constants';
 import {
   AnalyticsService,
   initializationPromisesMap,
@@ -47,7 +48,8 @@ import {
   setCurrentScreen as internalSetCurrentScreen,
   setUserId as internalSetUserId,
   setUserProperties as internalSetUserProperties,
-  setAnalyticsCollectionEnabled as internalSetAnalyticsCollectionEnabled
+  setAnalyticsCollectionEnabled as internalSetAnalyticsCollectionEnabled,
+  _setConsentDefaultForInit
 } from './functions';
 import { ERROR_FACTORY, AnalyticsError } from './errors';
 
@@ -716,3 +718,21 @@ export function logEvent(
  * @public
  */
 export type CustomEventName<T> = T extends EventNameString ? never : T;
+
+/**
+ * Sets the applicable end user consent state for this web app across all gtag references once
+ * Firebase Analytics is initialized.
+ *
+ * Use the {@link ConsentSettings} to specify individual consent type values. By default consent
+ * types are set to "granted".
+ *
+ * @param consentSettings Maps the applicable end user consent state for gtag.js.
+ */
+export function setConsent(consentSettings: ConsentSettings): void {
+  // Check if reference to existing gtag function on window object exists
+  if (wrappedGtagFunction) {
+    wrappedGtagFunction(GtagCommand.CONSENT, 'update', consentSettings);
+  } else {
+    _setConsentDefaultForInit(consentSettings);
+  }
+}

packages/analytics/src/constants.ts

@@ -34,5 +34,6 @@ export const GTAG_URL = 'https://www.googletagmanager.com/gtag/js';
 export const enum GtagCommand {
   EVENT = 'event',
   SET = 'set',
-  CONFIG = 'config'
+  CONFIG = 'config',
+  CONSENT = 'consent'
 }

packages/analytics/src/functions.ts

@@ -19,7 +19,8 @@ import {
   AnalyticsCallOptions,
   CustomParams,
   ControlParams,
-  EventParams
+  EventParams,
+  ConsentSettings
 } from './public-types';
 import { Gtag } from './types';
 import { GtagCommand } from './constants';
@@ -142,3 +143,27 @@ export async function setAnalyticsCollectionEnabled(
   const measurementId = await initializationPromise;
   window[`ga-disable-${measurementId}`] = !enabled;
 }
+
+/**
+ * Consent parameters to default to during 'gtag' initialization.
+ */
+export let defaultConsentSettingsForInit: ConsentSettings | undefined;
+
+/**
+ * Sets the variable {@link defaultConsentSettingsForInit} for use in the initialization of
+ * analytics.
+ *
+ * @param consentSettings Maps the applicable end user consent state for gtag.js.
+ */
+export function _setConsentDefaultForInit(
+  consentSettings: ConsentSettings
+): void {
+  if (defaultConsentSettingsForInit) {
+    defaultConsentSettingsForInit = {
+      ...defaultConsentSettingsForInit,
+      ...consentSettings
+    };
+  } else {
+    defaultConsentSettingsForInit = consentSettings;
+  }
+}

packages/analytics/src/helpers.ts

@@ -15,7 +15,12 @@
  * limitations under the License.
  */
 
-import { CustomParams, ControlParams, EventParams } from './public-types';
+import {
+  CustomParams,
+  ControlParams,
+  EventParams,
+  ConsentSettings
+} from './public-types';
 import { DynamicConfig, DataLayer, Gtag, MinimalDynamicConfig } from './types';
 import { GtagCommand, GTAG_URL } from './constants';
 import { logger } from './logger';
@@ -219,9 +224,10 @@ function wrapGtag(
    * @param gtagParams Params if event is EVENT/CONFIG.
    */
   async function gtagWrapper(
-    command: 'config' | 'set' | 'event',
+    command: 'config' | 'set' | 'event' | 'consent',
     idOrNameOrParams: string | ControlParams,
-    gtagParams?: ControlParams & EventParams & CustomParams
+    // TODO(dwyfrequency)Unsure if this is the best path.
+    gtagParams?: GtagSetConfigEventParams | ConsentSettings
   ): Promise<void> {
     try {
       // If event, check that relevant initialization promises have completed.
@@ -232,7 +238,7 @@ function wrapGtag(
           initializationPromisesMap,
           dynamicConfigPromisesList,
           idOrNameOrParams as string,
-          gtagParams
+          gtagParams as GtagSetConfigEventParams
         );
       } else if (command === GtagCommand.CONFIG) {
         // If CONFIG, second arg must be measurementId.
@@ -242,8 +248,11 @@ function wrapGtag(
           dynamicConfigPromisesList,
           measurementIdToAppId,
           idOrNameOrParams as string,
-          gtagParams
+          gtagParams as GtagSetConfigEventParams
         );
+      } else if (command === GtagCommand.CONSENT) {
+        // If CONFIG, second arg must be measurementId.
+        gtagCore(GtagCommand.CONSENT, 'update', gtagParams as ConsentSettings);
       } else {
         // If SET, second arg must be params.
         gtagCore(GtagCommand.SET, idOrNameOrParams as CustomParams);
@@ -254,6 +263,8 @@ function wrapGtag(
   }
   return gtagWrapper as Gtag;
 }
+// TODO(dwyfrequency)Unsure if this is the best path and where it should go. Probably the type file
+type GtagSetConfigEventParams = ControlParams & EventParams & CustomParams;
 
 /**
  * Creates global gtag function or wraps existing one if found.

packages/analytics/src/initialize-analytics.ts

@@ -28,6 +28,7 @@ import {
 import { ERROR_FACTORY, AnalyticsError } from './errors';
 import { findGtagScriptOnPage, insertScriptTag } from './helpers';
 import { AnalyticsSettings } from './public-types';
+import { defaultConsentSettingsForInit } from './functions';
 
 async function validateIndexedDB(): Promise<boolean> {
   if (!isIndexedDBAvailable()) {
@@ -118,6 +119,11 @@ export async function _initializeAnalytics(
     insertScriptTag(dataLayerName, dynamicConfig.measurementId);
   }
 
+  // Detects if there are consent settings that need to be configured.
+  if (defaultConsentSettingsForInit) {
+    gtagCore(GtagCommand.CONSENT, 'default', defaultConsentSettingsForInit);
+  }
+
   // This command initializes gtag.js and only needs to be called once for the entire web app,
   // but since it is idempotent, we can call it multiple times.
   // We keep it together with other initialization logic for better code structure.

packages/analytics/src/public-types.ts

@@ -288,4 +288,14 @@ export interface EventParams {
   page_path?: string;
   [key: string]: unknown;
 }
+
+/** Maps the applicable end user consent state. */
+export interface ConsentSettings {
+  ad_storage?: ConsentStatusString;
+  analytics_storage?: ConsentStatusString;
+}
+
 /* eslint-enable camelcase */
+
+/** Whether a particular consent type has been granted or denied. */
+export type ConsentStatusString = 'granted' | 'denied';

packages/analytics/src/types.ts

@@ -15,7 +15,12 @@
  * limitations under the License.
  */
 
-import { ControlParams, EventParams, CustomParams } from './public-types';
+import {
+  ControlParams,
+  EventParams,
+  CustomParams,
+  ConsentSettings
+} from './public-types';
 
 /**
  * Encapsulates metadata concerning throttled fetch requests.
@@ -63,6 +68,14 @@ export interface Gtag {
     eventName: string,
     eventParams?: ControlParams | EventParams | CustomParams
   ): void;
+  (
+    command: 'consent',
+    // TODO(dwyfrequency) should I make these subCommands their own type
+    subCommand: 'default' | 'update',
+    // TODO(dwyfrequency) should this be optional like eventParams and config.
+    // Idk why we would want it as optional
+    consentSettings: ConsentSettings
+  ): void;
 }
 
 export type DataLayer = IArguments[];