@firebase/analytics 0.7.11 → 0.8.0-20220706191717

package/CHANGELOG.md

@@ -1,5 +1,21 @@
 # @firebase/analytics
 
+## 0.8.0-20220706191717
+
+### Minor Changes
+
+- [`1d3a34d7d`](https://github.com/firebase/firebase-js-sdk/commit/1d3a34d7da5bf3c267d014efb587e03c46ff3064) [#6376](https://github.com/firebase/firebase-js-sdk/pull/6376) - Add function `setConsent()` to set the applicable end user "consent" state.
+
+* [`69e2ee064`](https://github.com/firebase/firebase-js-sdk/commit/69e2ee064e0729d8da823f1e60f6fb7f3bbe5700) [#6367](https://github.com/firebase/firebase-js-sdk/pull/6367) - Add function `setDefaultEventParameters()` to set data that will be logged on every Analytics SDK event
+
+### Patch Changes
+
+- Updated dependencies [[`b12af44a5`](https://github.com/firebase/firebase-js-sdk/commit/b12af44a5c7500e1192d6cc1a4afc4d77efadbaf)]:
+  - @firebase/util@1.6.3-20220706191717
+  - @firebase/app@0.7.28-20220706191717
+  - @firebase/component@0.5.17-20220706191717
+  - @firebase/installations@0.5.12-20220706191717
+
 ## 0.7.11
 
 ### Patch Changes

package/dist/analytics-public.d.ts

@@ -42,6 +42,38 @@ export declare interface AnalyticsSettings {
     config?: GtagConfigParams | EventParams;
 }
 
+/**
+ * Consent status settings for each consent type.
+ * For more information, see
+ * {@link https://developers.google.com/tag-platform/tag-manager/templates/consent-apis
+ * | the GA4 reference documentation for consent state and consent types}.
+ * @public
+ */
+export declare interface ConsentSettings {
+    /** Enables storage, such as cookies, related to advertising */
+    ad_storage?: ConsentStatusString;
+    /** Enables storage, such as cookies, related to analytics (for example, visit duration) */
+    analytics_storage?: ConsentStatusString;
+    /**
+     * Enables storage that supports the functionality of the website or app such as language settings
+     */
+    functionality_storage?: ConsentStatusString;
+    /** Enables storage related to personalization such as video recommendations */
+    personalization_storage?: ConsentStatusString;
+    /**
+     * Enables storage related to security such as authentication functionality, fraud prevention,
+     * and other user protection.
+     */
+    security_storage?: ConsentStatusString;
+    [key: string]: unknown;
+}
+
+/**
+ * Whether a particular consent type has been granted or denied.
+ * @public
+ */
+export declare type ConsentStatusString = 'granted' | 'denied';
+
 /**
  * Standard `gtag.js` control parameters.
  * For more information, see
@@ -637,6 +669,17 @@ export declare interface Promotion {
  */
 export declare function setAnalyticsCollectionEnabled(analyticsInstance: Analytics, enabled: boolean): void;
 
+/**
+ * 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".
+ * @public
+ * @param consentSettings - Maps the applicable end user consent state for gtag.js.
+ */
+export declare function setConsent(consentSettings: ConsentSettings): void;
+
 /**
  * Use gtag `config` command to set `screen_name`.
  *
@@ -650,6 +693,15 @@ export declare function setAnalyticsCollectionEnabled(analyticsInstance: Analyti
  */
 export declare function setCurrentScreen(analyticsInstance: Analytics, screenName: string, options?: AnalyticsCallOptions): void;
 
+/**
+ * Adds data that will be set on every event logged from the SDK, including automatic ones.
+ * With gtag's "set" command, the values passed persist on the current page and are passed with
+ * all subsequent events.
+ * @public
+ * @param customParams - Any custom params the user may pass to gtag.js.
+ */
+export declare function setDefaultEventParameters(customParams: CustomParams): void;
+
 /**
  * Configures Firebase Analytics to use custom `gtag` or `dataLayer` names.
  * Intended to be used if `gtag.js` script has been installed on

package/dist/analytics.d.ts

@@ -42,6 +42,38 @@ export declare interface AnalyticsSettings {
     config?: GtagConfigParams | EventParams;
 }
 
+/**
+ * Consent status settings for each consent type.
+ * For more information, see
+ * {@link https://developers.google.com/tag-platform/tag-manager/templates/consent-apis
+ * | the GA4 reference documentation for consent state and consent types}.
+ * @public
+ */
+export declare interface ConsentSettings {
+    /** Enables storage, such as cookies, related to advertising */
+    ad_storage?: ConsentStatusString;
+    /** Enables storage, such as cookies, related to analytics (for example, visit duration) */
+    analytics_storage?: ConsentStatusString;
+    /**
+     * Enables storage that supports the functionality of the website or app such as language settings
+     */
+    functionality_storage?: ConsentStatusString;
+    /** Enables storage related to personalization such as video recommendations */
+    personalization_storage?: ConsentStatusString;
+    /**
+     * Enables storage related to security such as authentication functionality, fraud prevention,
+     * and other user protection.
+     */
+    security_storage?: ConsentStatusString;
+    [key: string]: unknown;
+}
+
+/**
+ * Whether a particular consent type has been granted or denied.
+ * @public
+ */
+export declare type ConsentStatusString = 'granted' | 'denied';
+
 /**
  * Standard `gtag.js` control parameters.
  * For more information, see
@@ -637,6 +669,17 @@ export declare interface Promotion {
  */
 export declare function setAnalyticsCollectionEnabled(analyticsInstance: Analytics, enabled: boolean): void;
 
+/**
+ * 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".
+ * @public
+ * @param consentSettings - Maps the applicable end user consent state for gtag.js.
+ */
+export declare function setConsent(consentSettings: ConsentSettings): void;
+
 /**
  * Use gtag `config` command to set `screen_name`.
  *
@@ -650,6 +693,15 @@ export declare function setAnalyticsCollectionEnabled(analyticsInstance: Analyti
  */
 export declare function setCurrentScreen(analyticsInstance: Analytics, screenName: string, options?: AnalyticsCallOptions): void;
 
+/**
+ * Adds data that will be set on every event logged from the SDK, including automatic ones.
+ * With gtag's "set" command, the values passed persist on the current page and are passed with
+ * all subsequent events.
+ * @public
+ * @param customParams - Any custom params the user may pass to gtag.js.
+ */
+export declare function setDefaultEventParameters(customParams: CustomParams): void;
+
 /**
  * Configures Firebase Analytics to use custom `gtag` or `dataLayer` names.
  * Intended to be used if `gtag.js` script has been installed on

package/dist/esm/index.esm.js

@@ -277,8 +277,14 @@ measurementIdToAppId) {
                         _a.sent();
                         return [3 /*break*/, 5];
                     case 4:
-                        // If SET, second arg must be params.
-                        gtagCore("set" /* SET */, idOrNameOrParams);
+                        if (command === "consent" /* CONSENT */) {
+                            // If CONFIG, second arg must be measurementId.
+                            gtagCore("consent" /* CONSENT */, 'update', gtagParams);
+                        }
+                        else {
+                            // If SET, second arg must be params.
+                            gtagCore("set" /* SET */, idOrNameOrParams);
+                        }
                         _a.label = 5;
                     case 5: return [3 /*break*/, 7];
                     case 6:
@@ -662,6 +668,188 @@ var AnalyticsAbortSignal = /** @class */ (function () {
     return AnalyticsAbortSignal;
 }());
 
+/**
+ * @license
+ * Copyright 2019 Google LLC
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *   http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+/**
+ * Event parameters to set on 'gtag' during initialization.
+ */
+var defaultEventParametersForInit;
+/**
+ * Logs an analytics event through the Firebase SDK.
+ *
+ * @param gtagFunction Wrapped gtag function that waits for fid to be set before sending an event
+ * @param eventName Google Analytics event name, choose from standard list or use a custom string.
+ * @param eventParams Analytics event parameters.
+ */
+function logEvent$1(gtagFunction, initializationPromise, eventName, eventParams, options) {
+    return __awaiter(this, void 0, void 0, function () {
+        var measurementId, params;
+        return __generator(this, function (_a) {
+            switch (_a.label) {
+                case 0:
+                    if (!(options && options.global)) return [3 /*break*/, 1];
+                    gtagFunction("event" /* EVENT */, eventName, eventParams);
+                    return [2 /*return*/];
+                case 1: return [4 /*yield*/, initializationPromise];
+                case 2:
+                    measurementId = _a.sent();
+                    params = __assign(__assign({}, eventParams), { 'send_to': measurementId });
+                    gtagFunction("event" /* EVENT */, eventName, params);
+                    _a.label = 3;
+                case 3: return [2 /*return*/];
+            }
+        });
+    });
+}
+/**
+ * Set screen_name parameter for this Google Analytics ID.
+ *
+ * @deprecated Use {@link logEvent} with `eventName` as 'screen_view' and add relevant `eventParams`.
+ * See {@link https://firebase.google.com/docs/analytics/screenviews | Track Screenviews}.
+ *
+ * @param gtagFunction Wrapped gtag function that waits for fid to be set before sending an event
+ * @param screenName Screen name string to set.
+ */
+function setCurrentScreen$1(gtagFunction, initializationPromise, screenName, options) {
+    return __awaiter(this, void 0, void 0, function () {
+        var measurementId;
+        return __generator(this, function (_a) {
+            switch (_a.label) {
+                case 0:
+                    if (!(options && options.global)) return [3 /*break*/, 1];
+                    gtagFunction("set" /* SET */, { 'screen_name': screenName });
+                    return [2 /*return*/, Promise.resolve()];
+                case 1: return [4 /*yield*/, initializationPromise];
+                case 2:
+                    measurementId = _a.sent();
+                    gtagFunction("config" /* CONFIG */, measurementId, {
+                        update: true,
+                        'screen_name': screenName
+                    });
+                    _a.label = 3;
+                case 3: return [2 /*return*/];
+            }
+        });
+    });
+}
+/**
+ * Set user_id parameter for this Google Analytics ID.
+ *
+ * @param gtagFunction Wrapped gtag function that waits for fid to be set before sending an event
+ * @param id User ID string to set
+ */
+function setUserId$1(gtagFunction, initializationPromise, id, options) {
+    return __awaiter(this, void 0, void 0, function () {
+        var measurementId;
+        return __generator(this, function (_a) {
+            switch (_a.label) {
+                case 0:
+                    if (!(options && options.global)) return [3 /*break*/, 1];
+                    gtagFunction("set" /* SET */, { 'user_id': id });
+                    return [2 /*return*/, Promise.resolve()];
+                case 1: return [4 /*yield*/, initializationPromise];
+                case 2:
+                    measurementId = _a.sent();
+                    gtagFunction("config" /* CONFIG */, measurementId, {
+                        update: true,
+                        'user_id': id
+                    });
+                    _a.label = 3;
+                case 3: return [2 /*return*/];
+            }
+        });
+    });
+}
+/**
+ * Set all other user properties other than user_id and screen_name.
+ *
+ * @param gtagFunction Wrapped gtag function that waits for fid to be set before sending an event
+ * @param properties Map of user properties to set
+ */
+function setUserProperties$1(gtagFunction, initializationPromise, properties, options) {
+    return __awaiter(this, void 0, void 0, function () {
+        var flatProperties, _i, _a, key, measurementId;
+        return __generator(this, function (_b) {
+            switch (_b.label) {
+                case 0:
+                    if (!(options && options.global)) return [3 /*break*/, 1];
+                    flatProperties = {};
+                    for (_i = 0, _a = Object.keys(properties); _i < _a.length; _i++) {
+                        key = _a[_i];
+                        // use dot notation for merge behavior in gtag.js
+                        flatProperties["user_properties." + key] = properties[key];
+                    }
+                    gtagFunction("set" /* SET */, flatProperties);
+                    return [2 /*return*/, Promise.resolve()];
+                case 1: return [4 /*yield*/, initializationPromise];
+                case 2:
+                    measurementId = _b.sent();
+                    gtagFunction("config" /* CONFIG */, measurementId, {
+                        update: true,
+                        'user_properties': properties
+                    });
+                    _b.label = 3;
+                case 3: return [2 /*return*/];
+            }
+        });
+    });
+}
+/**
+ * Set whether collection is enabled for this ID.
+ *
+ * @param enabled If true, collection is enabled for this ID.
+ */
+function setAnalyticsCollectionEnabled$1(initializationPromise, enabled) {
+    return __awaiter(this, void 0, void 0, function () {
+        var measurementId;
+        return __generator(this, function (_a) {
+            switch (_a.label) {
+                case 0: return [4 /*yield*/, initializationPromise];
+                case 1:
+                    measurementId = _a.sent();
+                    window["ga-disable-" + measurementId] = !enabled;
+                    return [2 /*return*/];
+            }
+        });
+    });
+}
+/**
+ * Consent parameters to default to during 'gtag' initialization.
+ */
+var defaultConsentSettingsForInit;
+/**
+ * Sets the variable {@link defaultConsentSettingsForInit} for use in the initialization of
+ * analytics.
+ *
+ * @param consentSettings Maps the applicable end user consent state for gtag.js.
+ */
+function _setConsentDefaultForInit(consentSettings) {
+    defaultConsentSettingsForInit = consentSettings;
+}
+/**
+ * Sets the variable `defaultEventParametersForInit` for use in the initialization of
+ * analytics.
+ *
+ * @param customParams Any custom params the user may pass to gtag.js.
+ */
+function _setDefaultEventParametersForInit(customParams) {
+    defaultEventParametersForInit = customParams;
+}
+
 /**
  * @license
  * Copyright 2020 Google LLC
@@ -762,6 +950,11 @@ function _initializeAnalytics(app, dynamicConfigPromisesList, measurementIdToApp
                     if (!findGtagScriptOnPage()) {
                         insertScriptTag(dataLayerName, dynamicConfig.measurementId);
                     }
+                    // Detects if there are consent settings that need to be configured.
+                    if (defaultConsentSettingsForInit) {
+                        gtagCore("consent" /* CONSENT */, 'default', defaultConsentSettingsForInit);
+                        _setConsentDefaultForInit(undefined);
+                    }
                     // 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.
@@ -779,6 +972,11 @@ function _initializeAnalytics(app, dynamicConfigPromisesList, measurementIdToApp
                     // Note: This will trigger a page_view event unless 'send_page_view' is set to false in
                     // `configProperties`.
                     gtagCore("config" /* CONFIG */, dynamicConfig.measurementId, configProperties);
+                    // Detects if there is data that will be set on every event logged from the SDK.
+                    if (defaultEventParametersForInit) {
+                        gtagCore("set" /* SET */, defaultEventParametersForInit);
+                        _setDefaultEventParametersForInit(undefined);
+                    }
                     return [2 /*return*/, dynamicConfig.measurementId];
             }
         });
@@ -943,162 +1141,6 @@ function factory(app, installations, options) {
     return analyticsInstance;
 }
 
-/**
- * @license
- * Copyright 2019 Google LLC
- *
- * Licensed under the Apache License, Version 2.0 (the "License");
- * you may not use this file except in compliance with the License.
- * You may obtain a copy of the License at
- *
- *   http://www.apache.org/licenses/LICENSE-2.0
- *
- * Unless required by applicable law or agreed to in writing, software
- * distributed under the License is distributed on an "AS IS" BASIS,
- * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
- * See the License for the specific language governing permissions and
- * limitations under the License.
- */
-/**
- * Logs an analytics event through the Firebase SDK.
- *
- * @param gtagFunction Wrapped gtag function that waits for fid to be set before sending an event
- * @param eventName Google Analytics event name, choose from standard list or use a custom string.
- * @param eventParams Analytics event parameters.
- */
-function logEvent$1(gtagFunction, initializationPromise, eventName, eventParams, options) {
-    return __awaiter(this, void 0, void 0, function () {
-        var measurementId, params;
-        return __generator(this, function (_a) {
-            switch (_a.label) {
-                case 0:
-                    if (!(options && options.global)) return [3 /*break*/, 1];
-                    gtagFunction("event" /* EVENT */, eventName, eventParams);
-                    return [2 /*return*/];
-                case 1: return [4 /*yield*/, initializationPromise];
-                case 2:
-                    measurementId = _a.sent();
-                    params = __assign(__assign({}, eventParams), { 'send_to': measurementId });
-                    gtagFunction("event" /* EVENT */, eventName, params);
-                    _a.label = 3;
-                case 3: return [2 /*return*/];
-            }
-        });
-    });
-}
-/**
- * Set screen_name parameter for this Google Analytics ID.
- *
- * @deprecated Use {@link logEvent} with `eventName` as 'screen_view' and add relevant `eventParams`.
- * See {@link https://firebase.google.com/docs/analytics/screenviews | Track Screenviews}.
- *
- * @param gtagFunction Wrapped gtag function that waits for fid to be set before sending an event
- * @param screenName Screen name string to set.
- */
-function setCurrentScreen$1(gtagFunction, initializationPromise, screenName, options) {
-    return __awaiter(this, void 0, void 0, function () {
-        var measurementId;
-        return __generator(this, function (_a) {
-            switch (_a.label) {
-                case 0:
-                    if (!(options && options.global)) return [3 /*break*/, 1];
-                    gtagFunction("set" /* SET */, { 'screen_name': screenName });
-                    return [2 /*return*/, Promise.resolve()];
-                case 1: return [4 /*yield*/, initializationPromise];
-                case 2:
-                    measurementId = _a.sent();
-                    gtagFunction("config" /* CONFIG */, measurementId, {
-                        update: true,
-                        'screen_name': screenName
-                    });
-                    _a.label = 3;
-                case 3: return [2 /*return*/];
-            }
-        });
-    });
-}
-/**
- * Set user_id parameter for this Google Analytics ID.
- *
- * @param gtagFunction Wrapped gtag function that waits for fid to be set before sending an event
- * @param id User ID string to set
- */
-function setUserId$1(gtagFunction, initializationPromise, id, options) {
-    return __awaiter(this, void 0, void 0, function () {
-        var measurementId;
-        return __generator(this, function (_a) {
-            switch (_a.label) {
-                case 0:
-                    if (!(options && options.global)) return [3 /*break*/, 1];
-                    gtagFunction("set" /* SET */, { 'user_id': id });
-                    return [2 /*return*/, Promise.resolve()];
-                case 1: return [4 /*yield*/, initializationPromise];
-                case 2:
-                    measurementId = _a.sent();
-                    gtagFunction("config" /* CONFIG */, measurementId, {
-                        update: true,
-                        'user_id': id
-                    });
-                    _a.label = 3;
-                case 3: return [2 /*return*/];
-            }
-        });
-    });
-}
-/**
- * Set all other user properties other than user_id and screen_name.
- *
- * @param gtagFunction Wrapped gtag function that waits for fid to be set before sending an event
- * @param properties Map of user properties to set
- */
-function setUserProperties$1(gtagFunction, initializationPromise, properties, options) {
-    return __awaiter(this, void 0, void 0, function () {
-        var flatProperties, _i, _a, key, measurementId;
-        return __generator(this, function (_b) {
-            switch (_b.label) {
-                case 0:
-                    if (!(options && options.global)) return [3 /*break*/, 1];
-                    flatProperties = {};
-                    for (_i = 0, _a = Object.keys(properties); _i < _a.length; _i++) {
-                        key = _a[_i];
-                        // use dot notation for merge behavior in gtag.js
-                        flatProperties["user_properties." + key] = properties[key];
-                    }
-                    gtagFunction("set" /* SET */, flatProperties);
-                    return [2 /*return*/, Promise.resolve()];
-                case 1: return [4 /*yield*/, initializationPromise];
-                case 2:
-                    measurementId = _b.sent();
-                    gtagFunction("config" /* CONFIG */, measurementId, {
-                        update: true,
-                        'user_properties': properties
-                    });
-                    _b.label = 3;
-                case 3: return [2 /*return*/];
-            }
-        });
-    });
-}
-/**
- * Set whether collection is enabled for this ID.
- *
- * @param enabled If true, collection is enabled for this ID.
- */
-function setAnalyticsCollectionEnabled$1(initializationPromise, enabled) {
-    return __awaiter(this, void 0, void 0, function () {
-        var measurementId;
-        return __generator(this, function (_a) {
-            switch (_a.label) {
-                case 0: return [4 /*yield*/, initializationPromise];
-                case 1:
-                    measurementId = _a.sent();
-                    window["ga-disable-" + measurementId] = !enabled;
-                    return [2 /*return*/];
-            }
-        });
-    });
-}
-
 /* eslint-disable @typescript-eslint/no-explicit-any */
 /**
  * Returns an {@link Analytics} instance for the given app.
@@ -1230,6 +1272,22 @@ function setAnalyticsCollectionEnabled(analyticsInstance, enabled) {
     analyticsInstance = getModularInstance(analyticsInstance);
     setAnalyticsCollectionEnabled$1(initializationPromisesMap[analyticsInstance.app.options.appId], enabled).catch(function (e) { return logger.error(e); });
 }
+/**
+ * Adds data that will be set on every event logged from the SDK, including automatic ones.
+ * With gtag's "set" command, the values passed persist on the current page and are passed with
+ * all subsequent events.
+ * @public
+ * @param customParams - Any custom params the user may pass to gtag.js.
+ */
+function setDefaultEventParameters(customParams) {
+    // Check if reference to existing gtag function on window object exists
+    if (wrappedGtagFunction) {
+        wrappedGtagFunction("set" /* SET */, customParams);
+    }
+    else {
+        _setDefaultEventParametersForInit(customParams);
+    }
+}
 /**
  * Sends a Google Analytics event with given `eventParams`. This method
  * automatically associates this logged event with this Firebase web
@@ -1244,10 +1302,28 @@ function setAnalyticsCollectionEnabled(analyticsInstance, enabled) {
 function logEvent(analyticsInstance, eventName, eventParams, options) {
     analyticsInstance = getModularInstance(analyticsInstance);
     logEvent$1(wrappedGtagFunction, initializationPromisesMap[analyticsInstance.app.options.appId], eventName, eventParams, options).catch(function (e) { return logger.error(e); });
+}
+/**
+ * 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".
+ * @public
+ * @param consentSettings - Maps the applicable end user consent state for gtag.js.
+ */
+function setConsent(consentSettings) {
+    // Check if reference to existing gtag function on window object exists
+    if (wrappedGtagFunction) {
+        wrappedGtagFunction("consent" /* CONSENT */, 'update', consentSettings);
+    }
+    else {
+        _setConsentDefaultForInit(consentSettings);
+    }
 }
 
 var name = "@firebase/analytics";
-var version = "0.7.11";
+var version = "0.8.0-20220706191717";
 
 /**
  * Firebase Analytics
@@ -1284,5 +1360,5 @@ function registerAnalytics() {
 }
 registerAnalytics();
 
-export { getAnalytics, initializeAnalytics, isSupported, logEvent, setAnalyticsCollectionEnabled, setCurrentScreen, setUserId, setUserProperties, settings };
+export { getAnalytics, initializeAnalytics, isSupported, logEvent, setAnalyticsCollectionEnabled, setConsent, setCurrentScreen, setDefaultEventParameters, setUserId, setUserProperties, settings };
 //# sourceMappingURL=index.esm.js.map