Package analytics-exp (#4310)

Author: hsubox76

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

@@ -6,96 +6,36 @@
 
 import { Analytics } from '@firebase/analytics-types-exp';
 import { AnalyticsCallOptions } from '@firebase/analytics-types-exp';
+import { ControlParams } from '@firebase/analytics-types-exp';
 import { CustomParams } from '@firebase/analytics-types-exp';
-import { DynamicConfig } from '@firebase/analytics-types-exp';
 import { EventNameString } from '@firebase/analytics-types-exp';
 import { EventParams } from '@firebase/analytics-types-exp';
 import { FirebaseApp } from '@firebase/app-types-exp';
-import { _FirebaseInstallationsInternal } from '@firebase/installations-types-exp';
-import { _FirebaseService } from '@firebase/app-types-exp';
-import { MinimalDynamicConfig } from '@firebase/analytics-types-exp';
+import { Item } from '@firebase/analytics-types-exp';
+import { Promotion } from '@firebase/analytics-types-exp';
 import { SettingsOptions } from '@firebase/analytics-types-exp';
 
+export { Analytics }
+
+export { AnalyticsCallOptions }
+
+export { ControlParams }
+
 // @public
-export const enum EventName {
-    // (undocumented)
-    ADD_PAYMENT_INFO = "add_payment_info",
-    // (undocumented)
-    ADD_SHIPPING_INFO = "add_shipping_info",
-    // (undocumented)
-    ADD_TO_CART = "add_to_cart",
-    // (undocumented)
-    ADD_TO_WISHLIST = "add_to_wishlist",
-    // (undocumented)
-    BEGIN_CHECKOUT = "begin_checkout",
-    // @deprecated (undocumented)
-    CHECKOUT_PROGRESS = "checkout_progress",
-    // (undocumented)
-    EXCEPTION = "exception",
-    // (undocumented)
-    GENERATE_LEAD = "generate_lead",
-    // (undocumented)
-    LOGIN = "login",
-    // (undocumented)
-    PAGE_VIEW = "page_view",
-    // (undocumented)
-    PURCHASE = "purchase",
-    // (undocumented)
-    REFUND = "refund",
-    // (undocumented)
-    REMOVE_FROM_CART = "remove_from_cart",
-    // (undocumented)
-    SCREEN_VIEW = "screen_view",
-    // (undocumented)
-    SEARCH = "search",
-    // (undocumented)
-    SELECT_CONTENT = "select_content",
-    // (undocumented)
-    SELECT_ITEM = "select_item",
-    // (undocumented)
-    SELECT_PROMOTION = "select_promotion",
-    // @deprecated (undocumented)
-    SET_CHECKOUT_OPTION = "set_checkout_option",
-    // (undocumented)
-    SHARE = "share",
-    // (undocumented)
-    SIGN_UP = "sign_up",
-    // (undocumented)
-    TIMING_COMPLETE = "timing_complete",
-    // (undocumented)
-    VIEW_CART = "view_cart",
-    // (undocumented)
-    VIEW_ITEM = "view_item",
-    // (undocumented)
-    VIEW_ITEM_LIST = "view_item_list",
-    // (undocumented)
-    VIEW_PROMOTION = "view_promotion",
-    // (undocumented)
-    VIEW_SEARCH_RESULTS = "view_search_results"
-}
-
-// Warning: (ae-forgotten-export) The symbol "AnalyticsService" needs to be exported by the entry point index.d.ts
-// Warning: (ae-internal-missing-underscore) The name "factory" should be prefixed with an underscore because the declaration is marked as @internal
-//
-// @internal
-export function factory(app: FirebaseApp, installations: _FirebaseInstallationsInternal): AnalyticsService;
+export type CustomEventName<T> = T extends EventNameString ? never : T;
+
+export { CustomParams }
+
+export { EventParams }
 
 // @public
 export function getAnalytics(app: FirebaseApp): Analytics;
 
-// Warning: (ae-internal-missing-underscore) The name "getGlobalVars" should be prefixed with an underscore because the declaration is marked as @internal
-//
-// @internal
-export function getGlobalVars(): {
-    initializationPromisesMap: {
-        [appId: string]: Promise<string>;
-    };
-    dynamicConfigPromisesList: Array<Promise<DynamicConfig | MinimalDynamicConfig>>;
-};
-
 // @public
 export function isSupported(): Promise<boolean>;
 
+export { Item }
+
 // @public
 export function logEvent(analyticsInstance: Analytics, eventName: 'add_payment_info', eventParams?: {
     coupon?: EventParams['coupon'];
@@ -273,17 +213,12 @@ export function logEvent(analyticsInstance: Analytics, eventName: 'view_item_lis
     [key: string]: any;
 }, options?: AnalyticsCallOptions): void;
 
-// Warning: (ae-forgotten-export) The symbol "CustomEventName" needs to be exported by the entry point index.d.ts
-//
 // @public
 export function logEvent<T extends string>(analyticsInstance: Analytics, eventName: CustomEventName<T>, eventParams?: {
     [key: string]: any;
 }, options?: AnalyticsCallOptions): void;
 
-// Warning: (ae-internal-missing-underscore) The name "resetGlobalVars" should be prefixed with an underscore because the declaration is marked as @internal
-//
-// @internal
-export function resetGlobalVars(newGlobalInitDone?: boolean, newInitializationPromisesMap?: {}, newDynamicPromises?: never[]): void;
+export { Promotion }
 
 // @public
 export function setAnalyticsCollectionEnabled(analyticsInstance: Analytics, enabled: boolean): void;
@@ -294,6 +229,8 @@ export function setCurrentScreen(analyticsInstance: Analytics, screenName: strin
 // @public
 export function settings(options: SettingsOptions): void;
 
+export { SettingsOptions }
+
 // @public
 export function setUserId(analyticsInstance: Analytics, id: string, options?: AnalyticsCallOptions): void;
 

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

@@ -49,7 +49,6 @@ import {
 } from './functions';
 
 export { settings } from './factory';
-export { EventName } from './constants';
 
 declare module '@firebase/component' {
   interface NameServiceMapping {
@@ -674,4 +673,9 @@ export function logEvent(
   ).catch(e => logger.error(e));
 }
 
-type CustomEventName<T> = T extends EventNameString ? never : T;
+/**
+ * Any custom event name string not in the standard list of recommended
+ * event names.
+ * @public
+ */
+export type CustomEventName<T> = T extends EventNameString ? never : T;

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

@@ -36,47 +36,3 @@ export const enum GtagCommand {
   SET = 'set',
   CONFIG = 'config'
 }
-
-/**
- * Officially recommended event names for gtag.js
- * Any other string is also allowed.
- *
- * @public
- */
-export const enum EventName {
-  ADD_SHIPPING_INFO = 'add_shipping_info',
-  ADD_PAYMENT_INFO = 'add_payment_info',
-  ADD_TO_CART = 'add_to_cart',
-  ADD_TO_WISHLIST = 'add_to_wishlist',
-  BEGIN_CHECKOUT = 'begin_checkout',
-  /**
-   * @deprecated This event name is deprecated and is unsupported in updated
-   * Enhanced Ecommerce reports.
-   */
-  CHECKOUT_PROGRESS = 'checkout_progress',
-  EXCEPTION = 'exception',
-  GENERATE_LEAD = 'generate_lead',
-  LOGIN = 'login',
-  PAGE_VIEW = 'page_view',
-  PURCHASE = 'purchase',
-  REFUND = 'refund',
-  REMOVE_FROM_CART = 'remove_from_cart',
-  SCREEN_VIEW = 'screen_view',
-  SEARCH = 'search',
-  SELECT_CONTENT = 'select_content',
-  SELECT_ITEM = 'select_item',
-  SELECT_PROMOTION = 'select_promotion',
-  /**
-   * @deprecated This event name is deprecated and is unsupported in updated
-   * Enhanced Ecommerce reports.
-   */
-  SET_CHECKOUT_OPTION = 'set_checkout_option',
-  SHARE = 'share',
-  SIGN_UP = 'sign_up',
-  TIMING_COMPLETE = 'timing_complete',
-  VIEW_CART = 'view_cart',
-  VIEW_ITEM = 'view_item',
-  VIEW_ITEM_LIST = 'view_item_list',
-  VIEW_PROMOTION = 'view_promotion',
-  VIEW_SEARCH_RESULTS = 'view_search_results'
-}

packages-exp/analytics-exp/src/functions.test.ts

@@ -25,7 +25,7 @@ import {
   setUserProperties,
   setAnalyticsCollectionEnabled
 } from './functions';
-import { GtagCommand, EventName } from './constants';
+import { GtagCommand } from './constants';
 
 const fakeMeasurementId = 'abcd-efgh-ijkl';
 const fakeInitializationPromise = Promise.resolve(fakeMeasurementId);
@@ -38,57 +38,45 @@ describe('FirebaseAnalytics methods', () => {
   });
 
   it('logEvent() calls gtag function correctly', async () => {
-    await logEvent(gtagStub, fakeInitializationPromise, EventName.ADD_TO_CART, {
+    await logEvent(gtagStub, fakeInitializationPromise, 'add_to_cart', {
       currency: 'USD'
     });
 
-    expect(gtagStub).to.have.been.calledWith(
-      GtagCommand.EVENT,
-      EventName.ADD_TO_CART,
-      {
-        'send_to': fakeMeasurementId,
-        currency: 'USD'
-      }
-    );
+    expect(gtagStub).to.have.been.calledWith(GtagCommand.EVENT, 'add_to_cart', {
+      'send_to': fakeMeasurementId,
+      currency: 'USD'
+    });
   });
 
   it('logEvent() with no event params calls gtag function correctly', async () => {
-    await logEvent(gtagStub, fakeInitializationPromise, EventName.VIEW_ITEM);
+    await logEvent(gtagStub, fakeInitializationPromise, 'view_item');
 
-    expect(gtagStub).to.have.been.calledWith(
-      GtagCommand.EVENT,
-      EventName.VIEW_ITEM,
-      {
-        'send_to': fakeMeasurementId
-      }
-    );
+    expect(gtagStub).to.have.been.calledWith(GtagCommand.EVENT, 'view_item', {
+      'send_to': fakeMeasurementId
+    });
   });
 
   it('logEvent() globally calls gtag function correctly', async () => {
     await logEvent(
       gtagStub,
       fakeInitializationPromise,
-      EventName.ADD_TO_CART,
+      'add_to_cart',
       {
         currency: 'USD'
       },
       { global: true }
     );
 
-    expect(gtagStub).to.have.been.calledWith(
-      GtagCommand.EVENT,
-      EventName.ADD_TO_CART,
-      {
-        currency: 'USD'
-      }
-    );
+    expect(gtagStub).to.have.been.calledWith(GtagCommand.EVENT, 'add_to_cart', {
+      currency: 'USD'
+    });
   });
 
   it('logEvent() with no event params globally calls gtag function correctly', async () => {
     await logEvent(
       gtagStub,
       fakeInitializationPromise,
-      EventName.ADD_TO_CART,
+      'add_to_cart',
       undefined,
       {
         global: true
@@ -97,7 +85,7 @@ describe('FirebaseAnalytics methods', () => {
 
     expect(gtagStub).to.have.been.calledWith(
       GtagCommand.EVENT,
-      EventName.ADD_TO_CART,
+      'add_to_cart',
       undefined
     );
   });

packages-exp/analytics-exp/src/index.test.ts

@@ -18,24 +18,24 @@
 import { expect } from 'chai';
 import { SinonStub, stub, useFakeTimers } from 'sinon';
 import '../testing/setup';
-import {
-  settings,
-  factory as analyticsFactory,
-  resetGlobalVars,
-  getGlobalVars
-} from './index';
+import { settings } from './index';
 import {
   getFakeApp,
   getFakeInstallations
 } from '../testing/get-fake-firebase-services';
 import { FirebaseApp } from '@firebase/app-types-exp';
-import { GtagCommand, EventName } from './constants';
+import { GtagCommand } from './constants';
 import { findGtagScriptOnPage } from './helpers';
 import { removeGtagScript } from '../testing/gtag-script-util';
 import { Deferred } from '@firebase/util';
 import { AnalyticsError } from './errors';
 import { logEvent } from './api';
-import { AnalyticsService } from './factory';
+import {
+  AnalyticsService,
+  getGlobalVars,
+  resetGlobalVars,
+  factory as analyticsFactory
+} from './factory';
 import { _FirebaseInstallationsInternal } from '@firebase/installations-types-exp';
 
 let analyticsInstance: AnalyticsService = {} as AnalyticsService;
@@ -157,7 +157,7 @@ describe('FirebaseAnalytics instance tests', () => {
       expect(analyticsInstance.app).to.equal(app);
     });
     it('Calls gtag correctly on logEvent (instance)', async () => {
-      logEvent(analyticsInstance, EventName.ADD_PAYMENT_INFO, {
+      logEvent(analyticsInstance, 'add_payment_info', {
         currency: 'USD'
       });
       // Clear promise chain started by logEvent.
@@ -174,7 +174,7 @@ describe('FirebaseAnalytics instance tests', () => {
       );
       expect(gtagStub).to.have.been.calledWith(
         GtagCommand.EVENT,
-        EventName.ADD_PAYMENT_INFO,
+        'add_payment_info',
         {
           'send_to': 'abcd-efgh',
           currency: 'USD'
@@ -237,7 +237,7 @@ describe('FirebaseAnalytics instance tests', () => {
     it('Warns on logEvent if indexedDB API not available', async () => {
       const idbStub = stub(window, 'indexedDB').value(undefined);
       analyticsInstance = analyticsFactory(app, fakeInstallations);
-      logEvent(analyticsInstance, EventName.ADD_PAYMENT_INFO, {
+      logEvent(analyticsInstance, 'add_payment_info', {
         currency: 'USD'
       });
       // Clear promise chain started by logEvent.
@@ -257,7 +257,7 @@ describe('FirebaseAnalytics instance tests', () => {
       idbOpenStub.restore();
       idbOpenStub = stub(indexedDB, 'open').throws('idb open error test');
       analyticsInstance = analyticsFactory(app, fakeInstallations);
-      logEvent(analyticsInstance, EventName.ADD_PAYMENT_INFO, {
+      logEvent(analyticsInstance, 'add_payment_info', {
         currency: 'USD'
       });
       // Clear promise chain started by logEvent.
@@ -307,7 +307,7 @@ describe('FirebaseAnalytics instance tests', () => {
       idbOpenStub.restore();
     });
     it('Calls gtag correctly on logEvent (instance)', async () => {
-      logEvent(analyticsInstance, EventName.ADD_PAYMENT_INFO, {
+      logEvent(analyticsInstance, 'add_payment_info', {
         currency: 'USD'
       });
       // Clear promise chain started by logEvent.
@@ -324,7 +324,7 @@ describe('FirebaseAnalytics instance tests', () => {
       );
       expect(gtagStub).to.have.been.calledWith(
         GtagCommand.EVENT,
-        EventName.ADD_PAYMENT_INFO,
+        'add_payment_info',
         {
           'send_to': 'abcd-efgh',
           currency: 'USD'