Issue 2393 - Add environment check to Analytics Module

.changeset/clean-numbers-flow.md

@@ -0,0 +1,9 @@
+---
+"@firebase/analytics": minor
+"firebase": minor
+---
+
+Issue 2393 fix - analytics module
+
+- Added a public method `isSupported` to Analytics module which returns true if current browser context supports initialization of analytics module.
+- Added runtime checks to Analytics module that validate if cookie is enabled in current browser and if current browser environment supports indexedDB functionalities. 

packages/analytics/index.ts

@@ -32,7 +32,11 @@ import {
   ComponentContainer
 } from '@firebase/component';
 import { ERROR_FACTORY, AnalyticsError } from './src/errors';
-
+import {
+  isIndexedDBAvailable,
+  validateIndexedDBOpenable,
+  isCookieEnabled
+} from '@firebase/util';
 import { name, version } from './package.json';
 
 declare global {
@@ -45,6 +49,7 @@ declare global {
  * Type constant for Firebase Analytics.
  */
 const ANALYTICS_TYPE = 'analytics';
+
 export function registerAnalytics(instance: _FirebaseNamespace): void {
   instance.INTERNAL.registerComponent(
     new Component(
@@ -55,13 +60,13 @@ export function registerAnalytics(instance: _FirebaseNamespace): void {
         const installations = container
           .getProvider('installations')
           .getImmediate();
-
         return factory(app, installations);
       },
       ComponentType.PUBLIC
     ).setServiceProps({
       settings,
-      EventName
+      EventName,
+      isSupported
     })
   );
 
@@ -97,8 +102,31 @@ registerAnalytics(firebase as _FirebaseNamespace);
 declare module '@firebase/app-types' {
   interface FirebaseNamespace {
     analytics(app?: FirebaseApp): FirebaseAnalytics;
+    isSupported(): Promise<boolean>;
   }
   interface FirebaseApp {
     analytics(): FirebaseAnalytics;
   }
 }
+
+/**
+ * this is a public static method provided to users that wraps three different checks:
+ *
+ * 1. check if cookie is enabled in current browser.
+ * 2. check if IndexedDB is supported by the browser environment.
+ * 3. check if the current browser context is valid for using IndexedDB.
+ */
+async function isSupported(): Promise<boolean> {
+  if (!isCookieEnabled()) {
+    return false;
+  }
+  if (!isIndexedDBAvailable()) {
+    return false;
+  }
+  try {
+    const isDBOpenable: boolean = await validateIndexedDBOpenable();
+    return isDBOpenable;
+  } catch (error) {
+    return false;
+  }
+}

packages/analytics/package.json

@@ -56,4 +56,4 @@
     ],
     "reportDir": "./coverage/node"
   }
-}
+}

packages/analytics/src/errors.ts

@@ -22,7 +22,10 @@ export const enum AnalyticsError {
   NO_GA_ID = 'no-ga-id',
   ALREADY_EXISTS = 'already-exists',
   ALREADY_INITIALIZED = 'already-initialized',
-  INTEROP_COMPONENT_REG_FAILED = 'interop-component-reg-failed'
+  INTEROP_COMPONENT_REG_FAILED = 'interop-component-reg-failed',
+  INDEXED_DB_UNSUPPORTED = 'indexedDB-unsupported',
+  INVALID_INDEXED_DB_CONTEXT = 'invalid-indexedDB-context',
+  COOKIE_NOT_ENABLED = 'cookie-not-enabled'
 }
 
 const ERRORS: ErrorMap<AnalyticsError> = {
@@ -39,12 +42,19 @@ const ERRORS: ErrorMap<AnalyticsError> = {
     'settings() must be called before initializing any Analytics instance' +
     'or it will have no effect.',
   [AnalyticsError.INTEROP_COMPONENT_REG_FAILED]:
-    'Firebase Analytics Interop Component failed to instantiate'
+    'Firebase Analytics Interop Component failed to instantiate',
+  [AnalyticsError.INDEXED_DB_UNSUPPORTED]:
+    'IndexedDB is not supported by current browswer',
+  [AnalyticsError.INVALID_INDEXED_DB_CONTEXT]:
+    "Environment doesn't support IndexedDB: {$errorInfo}. Wrap initialization of analytics in analytics.isSupported() to prevent intialization in unsupported environments",
+  [AnalyticsError.COOKIE_NOT_ENABLED]:
+    'Cookie not enabled in this browser environment. Analytics requires cookies to be enabled.'
 };
 
 interface ErrorParams {
   [AnalyticsError.ALREADY_EXISTS]: { id: string };
   [AnalyticsError.INTEROP_COMPONENT_REG_FAILED]: { reason: Error };
+  [AnalyticsError.INVALID_INDEXED_DB_CONTEXT]: { errorInfo: string };
 }
 
 export const ERROR_FACTORY = new ErrorFactory<AnalyticsError, ErrorParams>(

packages/analytics/src/factory.ts

@@ -32,7 +32,8 @@ import {
   insertScriptTag,
   getOrCreateDataLayer,
   wrapOrCreateGtag,
-  findGtagScriptOnPage
+  findGtagScriptOnPage,
+  validateInitializationEnvironment
 } from './helpers';
 import { ANALYTICS_ID_FIELD } from './constants';
 import { AnalyticsError, ERROR_FACTORY } from './errors';
@@ -117,6 +118,10 @@ export function factory(
   app: FirebaseApp,
   installations: FirebaseInstallations
 ): FirebaseAnalytics {
+  // Async but non-blocking.
+  // eslint-disable-next-line @typescript-eslint/no-floating-promises
+  validateInitializationEnvironment();
+
   const analyticsId = app.options[ANALYTICS_ID_FIELD];
   if (!analyticsId) {
     throw ERROR_FACTORY.create(AnalyticsError.NO_GA_ID);

packages/analytics/src/helpers.ts

@@ -32,7 +32,12 @@ import {
 } from './constants';
 import { FirebaseInstallations } from '@firebase/installations-types';
 import { logger } from './logger';
-
+import { ERROR_FACTORY, AnalyticsError } from './errors';
+import {
+  isIndexedDBAvailable,
+  validateIndexedDBOpenable,
+  isCookieEnabled
+} from '@firebase/util';
 /**
  * Initialize the analytics instance in gtag.js by calling config command with fid.
  *
@@ -218,3 +223,27 @@ export function findGtagScriptOnPage(): HTMLScriptElement | null {
   }
   return null;
 }
+
+/**
+ * This method checks whether cookie is enabled within current browser and throws AnalyticsError.COOKIE_NOT_ENABLED if not.
+ *
+ * This method also checks if indexedDB is supported by current browser and throws AnalyticsError.INDEXED_DB_UNSUPPORTED error if not.
+ *
+ * This method also validates browser context for indexedDB by opening a dummy indexedDB database and throws AnalyticsError.INVALID_INDEXED_DB_CONTEXT
+ * if errors occur during the database open operation.
+ */
+export async function validateInitializationEnvironment(): Promise<void> {
+  if (!isCookieEnabled()) {
+    throw ERROR_FACTORY.create(AnalyticsError.COOKIE_NOT_ENABLED);
+  }
+  if (!isIndexedDBAvailable()) {
+    throw ERROR_FACTORY.create(AnalyticsError.INDEXED_DB_UNSUPPORTED);
+  }
+  try {
+    await validateIndexedDBOpenable();
+  } catch (error) {
+    throw ERROR_FACTORY.create(AnalyticsError.INVALID_INDEXED_DB_CONTEXT, {
+      errorInfo: error
+    });
+  }
+}

packages/firebase/index.d.ts

@@ -5083,6 +5083,16 @@ declare namespace firebase.analytics {
     id?: string;
     name?: string;
   }
+
+  /**
+   * An async function that returns true if current browser context supports initialization of analytics module
+   * (`firebase.analytics()`).
+   *
+   * Returns false otherwise.
+   *
+   *
+   */
+  function isSupported(): Promise<boolean>;
 }
 
 declare namespace firebase.auth.Auth {

packages/util/src/environment.ts

@@ -134,3 +134,58 @@ export function isSafari(): boolean {
     !navigator.userAgent.includes('Chrome')
   );
 }
+
+/**
+ * This method checks if indexedDB is supported by current browser
+ * @return true if indexedDB is supported by current browser
+ */
+export function isIndexedDBAvailable(): boolean {
+  if (!('indexedDB' in window) || indexedDB === null) {
+    return false;
+  }
+  return true;
+}
+
+/**
+ * This method validates browser context for indexedDB by opening a dummy indexedDB database and reject
+ * if errors occur during the database open operation.
+ */
+export function validateIndexedDBOpenable(): Promise<boolean> {
+  return new Promise((resolve, reject) => {
+    try {
+      let preExist: boolean = true;
+      const DB_CHECK_NAME =
+        'validate-browser-context-for-indexeddb-analytics-module';
+      const request = window.indexedDB.open(DB_CHECK_NAME);
+      request.onsuccess = () => {
+        request.result.close();
+        // delete database only when it doesn't pre-exist
+        if (!preExist) {
+          window.indexedDB.deleteDatabase(DB_CHECK_NAME);
+        }
+        resolve(true);
+      };
+      request.onupgradeneeded = () => {
+        preExist = false;
+      };
+
+      request.onerror = () => {
+        reject(request.error?.message || '');
+      };
+    } catch (error) {
+      reject(error);
+    }
+  });
+}
+
+/**
+ *
+ * This method checks whether cookie is enabled within current browser
+ * @return true if cookie is enabled within current browser
+ */
+export function isCookieEnabled(): boolean {
+  if (!navigator || !navigator.cookieEnabled) {
+    return false;
+  }
+  return true;
+}