Fix tests and type comments

Author: hsubox76

common/api-review/analytics-exp.api.md

@@ -6,7 +6,7 @@
 
 import { FirebaseApp } from '@firebase/app-exp';
 
-// @public (undocumented)
+// @public
 export interface Analytics {
     app: FirebaseApp;
 }
@@ -16,6 +16,12 @@ export interface AnalyticsCallOptions {
     global: boolean;
 }
 
+// @public
+export interface AnalyticsOptions {
+    // (undocumented)
+    config: GtagConfigParams | EventParams;
+}
+
 // @public
 export interface ControlParams {
     // (undocumented)
@@ -45,6 +51,8 @@ export type EventNameString = 'add_payment_info' | 'add_shipping_info' | 'add_to
 
 // @public
 export interface EventParams {
+    // (undocumented)
+    [key: string]: unknown;
     // (undocumented)
     affiliation?: string;
     // (undocumented)
@@ -110,6 +118,45 @@ export interface EventParams {
 // @public
 export function getAnalytics(app: FirebaseApp): Analytics;
 
+// @public
+export interface GtagConfigParams {
+    // (undocumented)
+    'allow_google_signals?': boolean;
+    // (undocumented)
+    [key: string]: unknown;
+    // (undocumented)
+    'allow_ad_personalization_signals'?: boolean;
+    // (undocumented)
+    'anonymize_ip'?: boolean;
+    // (undocumented)
+    'cookie_domain'?: string;
+    // (undocumented)
+    'cookie_expires'?: number;
+    // (undocumented)
+    'cookie_flags'?: string;
+    // (undocumented)
+    'cookie_prefix'?: string;
+    // (undocumented)
+    'cookie_update'?: boolean;
+    // (undocumented)
+    'custom_map'?: {
+        [key: string]: unknown;
+    };
+    // (undocumented)
+    'link_attribution'?: boolean;
+    // (undocumented)
+    'page_location'?: string;
+    // (undocumented)
+    'page_path'?: string;
+    // (undocumented)
+    'page_title'?: string;
+    // (undocumented)
+    'send_page_view'?: boolean;
+}
+
+// @public
+export function initializeAnalytics(app: FirebaseApp, options?: AnalyticsOptions): Analytics;
+
 // @public
 export function isSupported(): Promise<boolean>;
 

packages-exp/analytics-exp/src/api.ts

@@ -48,6 +48,7 @@ import {
   setUserProperties as internalSetUserProperties,
   setAnalyticsCollectionEnabled as internalSetAnalyticsCollectionEnabled
 } from './functions';
+import { ERROR_FACTORY, AnalyticsError } from './errors';
 
 export { settings } from './factory';
 
@@ -95,9 +96,7 @@ export function initializeAnalytics(
     ANALYTICS_TYPE
   );
   if (analyticsProvider.isInitialized()) {
-    return analyticsProvider.getImmediate();
-    // TODO: Throw an analytics specific error.
-    // _fail(analyticsInstance, AuthErrorCode.ALREADY_INITIALIZED);
+    throw ERROR_FACTORY.create(AnalyticsError.ALREADY_INITIALIZED);
   }
   const analyticsInstance = analyticsProvider.getImmediate();
   // do init settings stuff here

packages-exp/analytics-exp/src/errors.ts

@@ -20,6 +20,7 @@ import { ErrorFactory, ErrorMap } from '@firebase/util';
 export const enum AnalyticsError {
   ALREADY_EXISTS = 'already-exists',
   ALREADY_INITIALIZED = 'already-initialized',
+  ALREADY_INITIALIZED_SETTINGS = 'already-initialized-settings',
   INTEROP_COMPONENT_REG_FAILED = 'interop-component-reg-failed',
   INVALID_ANALYTICS_CONTEXT = 'invalid-analytics-context',
   INDEXEDDB_UNAVAILABLE = 'indexeddb-unavailable',
@@ -35,6 +36,10 @@ const ERRORS: ErrorMap<AnalyticsError> = {
     ' already exists. ' +
     'Only one Firebase Analytics instance can be created for each appId.',
   [AnalyticsError.ALREADY_INITIALIZED]:
+    'Firebase Analytics has already been initialized. ' +
+    'initializeAnalytics() must only be called once. getAnalytics() can be used ' +
+    'to get a reference to the already-intialized instance.',
+  [AnalyticsError.ALREADY_INITIALIZED_SETTINGS]:
     'Firebase Analytics has already been initialized.' +
     'settings() must be called before initializing any Analytics instance' +
     'or it will have no effect.',

packages-exp/analytics-exp/src/factory.ts

@@ -136,7 +136,7 @@ export function getGlobalVars(): {
  */
 export function settings(options: SettingsOptions): void {
   if (globalInitDone) {
-    throw ERROR_FACTORY.create(AnalyticsError.ALREADY_INITIALIZED);
+    throw ERROR_FACTORY.create(AnalyticsError.ALREADY_INITIALIZED_SETTINGS);
   }
   if (options.dataLayerName) {
     dataLayerName = options.dataLayerName;

packages-exp/analytics-exp/src/public-types.ts

@@ -20,6 +20,7 @@ import { FirebaseApp } from '@firebase/app-exp';
 /**
  * A set of common Analytics config settings recognized by
  * gtag.
+ * @public
  */
 export interface GtagConfigParams {
   'send_page_view'?: boolean;
@@ -41,6 +42,7 @@ export interface GtagConfigParams {
 
 /**
  * Analytics initialization options.
+ * @public
  */
 export interface AnalyticsOptions {
   config: GtagConfigParams | EventParams;
@@ -49,6 +51,7 @@ export interface AnalyticsOptions {
 /**
  * Additional options that can be passed to Firebase Analytics method
  * calls such as `logEvent`, `setCurrentScreen`, etc.
+ * @public
  */
 export interface AnalyticsCallOptions {
   /**
@@ -58,6 +61,10 @@ export interface AnalyticsCallOptions {
   global: boolean;
 }
 
+/**
+ * An instance of Firebase Analytics.
+ * @public
+ */
 export interface Analytics {
   /**
    * The FirebaseApp this Functions instance is associated with.
@@ -68,6 +75,7 @@ export interface Analytics {
 /**
  * Specifies custom options for your Firebase Analytics instance.
  * You must set these before initializing `firebase.analytics()`.
+ * @public
  */
 export interface SettingsOptions {
   /** Sets custom name for `gtag` function. */
@@ -78,13 +86,15 @@ export interface SettingsOptions {
 
 /**
  * Any custom params the user may pass to gtag.js.
+ * @public
  */
 export interface CustomParams {
   [key: string]: unknown;
 }
 /**
  * Type for standard gtag.js event names. `logEvent` also accepts any
  * custom string and interprets it as a custom event name.
+ * @public
  */
 export type EventNameString =
   | 'add_payment_info'
@@ -115,9 +125,15 @@ export type EventNameString =
   | 'view_promotion'
   | 'view_search_results';
 
+/**
+ * @public
+ */
 export type Currency = string | number;
 
 /* eslint-disable camelcase */
+/**
+ * @public
+ */
 export interface Item {
   item_id?: string;
   item_name?: string;
@@ -151,7 +167,10 @@ export interface Item {
   name?: string;
 }
 
-/** @deprecated Use Item instead. */
+/**
+ * @deprecated Use Item instead.
+ * @public
+ */
 export interface Promotion {
   creative_name?: string;
   creative_slot?: string;
@@ -164,6 +183,7 @@ export interface Promotion {
  * For more information, see
  * {@link https://developers.google.com/gtagjs/reference/parameter
  * | the gtag.js documentation on parameters}.
+ * @public
  */
 export interface ControlParams {
   groups?: string | string[];
@@ -177,6 +197,7 @@ export interface ControlParams {
  * For more information, see
  * {@link https://developers.google.com/gtagjs/reference/parameter
  * | the gtag.js documentation on parameters}.
+ * @public
  */
 export interface EventParams {
   checkout_option?: string;

packages-exp/analytics-exp/testing/integration-tests/integration.ts

@@ -17,10 +17,11 @@
 
 import { initializeApp, deleteApp, FirebaseApp } from '@firebase/app-exp';
 import '@firebase/installations-exp';
-import { getAnalytics, logEvent } from '../../src/index';
+import { getAnalytics, initializeAnalytics, logEvent } from '../../src/index';
 import '../setup';
 import { expect } from 'chai';
 import { stub } from 'sinon';
+import { AnalyticsError } from '../../src/errors';
 
 let config: Record<string, string>;
 try {
@@ -36,36 +37,70 @@ const RETRY_INTERVAL = 1000;
 
 describe('FirebaseAnalytics Integration Smoke Tests', () => {
   let app: FirebaseApp;
-  afterEach(() => deleteApp(app));
-  it('logEvent() sends correct network request.', async () => {
-    app = initializeApp(config);
-    logEvent(getAnalytics(app), 'login', { method: 'email' });
-    async function checkForEventCalls(): Promise<number> {
-      await new Promise(resolve => setTimeout(resolve, RETRY_INTERVAL));
-      const resources = performance.getEntriesByType('resource');
-      const callsWithEvent = resources.filter(
-        resource =>
-          resource.name.includes('google-analytics.com') &&
-          resource.name.includes('en=login')
-      );
-      if (callsWithEvent.length === 0) {
-        return checkForEventCalls();
-      } else {
-        return callsWithEvent.length;
+  describe('Using getAnalytics()', () => {
+    afterEach(() => deleteApp(app));
+    it('logEvent() sends correct network request.', async () => {
+      app = initializeApp(config);
+      logEvent(getAnalytics(app), 'login', { method: 'email' });
+      async function checkForEventCalls(): Promise<number> {
+        await new Promise(resolve => setTimeout(resolve, RETRY_INTERVAL));
+        const resources = performance.getEntriesByType('resource');
+        const callsWithEvent = resources.filter(
+          resource =>
+            resource.name.includes('google-analytics.com') &&
+            resource.name.includes('en=login')
+        );
+        if (callsWithEvent.length === 0) {
+          return checkForEventCalls();
+        } else {
+          return callsWithEvent.length;
+        }
       }
-    }
-    const eventCallCount = await checkForEventCalls();
-    expect(eventCallCount).to.equal(1);
+      const eventCallCount = await checkForEventCalls();
+      expect(eventCallCount).to.equal(1);
+    });
+    it("Warns if measurement ID doesn't match.", done => {
+      const warnStub = stub(console, 'warn').callsFake(() => {
+        expect(warnStub.args[0][1]).to.include('does not match');
+        done();
+      });
+      app = initializeApp({
+        ...config,
+        measurementId: 'wrong-id'
+      });
+      getAnalytics(app);
+    });
   });
-  it("Warns if measurement ID doesn't match.", done => {
-    const warnStub = stub(console, 'warn').callsFake(() => {
-      expect(warnStub.args[0][1]).to.include('does not match');
-      done();
+  describe('Using initializeAnalytics()', () => {
+    it('logEvent() sends correct network request.', async () => {
+      app = initializeApp(config);
+      logEvent(initializeAnalytics(app), 'login', { method: 'email' });
+      async function checkForEventCalls(): Promise<number> {
+        await new Promise(resolve => setTimeout(resolve, RETRY_INTERVAL));
+        const resources = performance.getEntriesByType('resource');
+        const callsWithEvent = resources.filter(
+          resource =>
+            resource.name.includes('google-analytics.com') &&
+            resource.name.includes('en=login')
+        );
+        if (callsWithEvent.length === 0) {
+          return checkForEventCalls();
+        } else {
+          return callsWithEvent.length;
+        }
+      }
+      const eventCallCount = await checkForEventCalls();
+      expect(eventCallCount).to.equal(1);
+    });
+    it('getAnalytics() does not throw if called after initializeAnalytics().', async () => {
+      const analyticsInstance = getAnalytics(app);
+      expect(analyticsInstance.app).to.equal(app);
     });
-    app = initializeApp({
-      ...config,
-      measurementId: 'wrong-id'
+    it('initializeAnalytics() throws if called more than once.', async () => {
+      expect(() => initializeAnalytics(app)).to.throw(
+        AnalyticsError.ALREADY_INITIALIZED
+      );
+      await deleteApp(app);
     });
-    getAnalytics(app);
   });
 });