fleek-track-analytics 0.0.93 → 0.0.94

package/README.md

@@ -0,0 +1,193 @@
+# fleek-track-analytics
+
+fleek-track-analytics provides multiplatform support for integrating a type safe event tracking mechanism. The library provides web, node and react-native utils to initialise and track events
+with trace(session) management.
+
+### Table of Contents
+
+- [How to integrate](#how-to-integrate)
+- [How to setup for development](#how-to-setup-for-development)
+- [How to change event map](#how-to-change-event-map)
+- [How to publish changes to npm](#how-to-publish-changes-to-npm)
+
+---
+
+# How to Integrate
+
+1. Install the package
+```sh
+# npm
+npm install fleek-track-analytics
+
+# yarn
+yarn add fleek-track-analytics
+```
+
+2. Import based on platform
+```ts
+# node
+import { TrackAnalytics } from "fleek-track-analytics/lib/node";
+
+#web
+import { TrackAnalytics } from "fleek-track-analytics/lib/web";
+
+#react-native
+import { TrackAnalytics } from "fleek-track-analytics/lib/web";
+```
+
+3. Initialise TrackAnalytics.
+
+  ```ts
+import { TrackAnalytics } from 'fleek-track-analytics/lib/__platform__';
+
+const analyticsException = (e: unknown) => {
+  if (__DEV__) {
+    console.error(JSON.stringify(e));
+  } else {
+    // Note: you can log the errors to production error reporting
+    Sentry.captureException(e);
+  }
+};
+
+const analyticsWrapper = new TrackAnalytics({
+  platform: 'REACT_NATIVE',
+  App: 'CONSUMER_APP',
+  segment: true,
+  segmentKey: process.env.EXPO_PUBLIC_SEGMENT_KEY || '', //provide the segment key 
+  devMode: __DEV__,
+  errorHandler: analyticsException,
+});
+
+analyticsWrapper.initAnalytics();
+```
+
+Parameter description for TrackAnalytics class constructor
+
+| property        | value           | description  |
+| ------------- |:-------------:| ----- |
+| platfrom     | `REACT_NATIVE` , `WEB`, `NODE`    | this is used for internal working of analytics to  |
+| App      | `CUSTOMER_APP`, `CUSTOMER_WEB`, `VENDOR_APP`       |   this property is send with all events as `fleek_platform` |
+| segment | boolean     |    enables segment integration |
+| segmentKey | string     |   writeKey for segment |
+| devMode | boolean     |   if enabled, only log the event do not trigger network calls |
+| debug | boolean      |  if enabled, triggers network calls for events when devMode is true.  |
+| errorHandler | function     | an error handler to manage any errors thrown while initialising and sending events  |
+
+4. Use the intialised instance in your app to send events by using the Event Names
+
+```ts
+import { analyticsWrapper } from '../utils/track-analytics';
+import { EVENT_NAMES } from 'fleek-track-analytics'
+
+analyticsWrapper.track(EVENT_NAMES.HOME_SCREEN_VIEWED, {
+      customer_id: AuthInfo.getAuthData().user?.customerId,
+      access_country: props?.responseHeaders?.resolvedCountryCode,
+    })
+```
+
+Note: Each event name is configured to have specify param type defination via `EVENT_MAP`. In the example above, if one more property is added in the parameters, the typescript will error. 
+How to declare events in the `EVENT_MAP` is explained here.  
+
+You can also use the base events given by segment smillarly 
+
+```ts
+
+analytics.identify(id , traits)
+
+analyticsWrapper.page({ name: pageName }) // web
+analyticsWrapper.screen(name, options) // react-native
+
+```
+
+# How to setup for development
+
+1. Clone the repository
+
+2. Run
+```sh
+yarn && yarn build
+
+```
+
+3. Login to npm with fleek credentials. (Acquire the credentials from the team members)
+
+
+# How to publish changes to npm 
+
+1. After updating the code, change the package json to a new version based on following rules
+- If changes in library code upgrade as minor release patch. Example `1.1.20` to `1.2.20`
+- If changes in eventmap upgrade as patch. Example `1.2.20` to `1.2.21`
+
+2. Build and publish
+```sh
+yarn build && npm publish
+``
+
+# How to update event map
+
+In order to build reliability in event data consistency across platform, `.track()` function expets event name and event properties to be type defined before use. The function defination for track is hence, 
+
+```ts
+type track = <T extends EVENT_NAMES>(eventName: T, eventParams: EVENT_MAP[T]) => Promise<void> | void
+```
+
+# How to change event map 
+
+1. Setup the the fleek-track-analytics repo by steps given here.
+
+2. To add a new events, create a enum entry in EVENT_NAMES by updating `src/event-map/event-map.ts`
+
+ ```ts
+// src/event-map/event-map.ts
+
+export enum EVENT_NAMES {
+  HOME_SCREEN_VIEWED = 'homescreen_viewed',
+  PRODUCT_TILE_CLICKED = 'product_tile_clicked',
+  PRODUCT_DETAIL_PAGE_VIEWED = 'product_detail_page_viewed',
+  ADD_TO_CART = 'add_to_cart',
+  CART_VIEWED = 'cart_viewed',
+  CHECKOUT_CLICKED = 'checkout_clicked',
+  // add a new event name
+  MY_NEW_EVENT = 'my_new_event
+}
+```
+
+3. Create a event params defination for your event in a new file in folder `src/event-map/event-data-type`
+
+```ts
+src/event-map/event-data-types/my-new-event.ts
+
+export interface IMyNewEvent {
+  id: string;
+  city: string,
+  prop1: number,
+  prop2: boolean  
+}
+
+```
+
+4. Add the mapping of event name and params in `src/event-map/event-map.ts`
+
+```ts
+  export interface EVENT_MAP {
+  [EVENT_NAMES.HOME_SCREEN_VIEWED]: IHomeScreenViewed;
+  [EVENT_NAMES.PRODUCT_TILE_CLICKED]: IProductTileClicked;
+  [EVENT_NAMES.PRODUCT_DETAIL_PAGE_VIEWED]: IProductDetailPageViewed;
+  [EVENT_NAMES.ADD_TO_CART]: IAddToCart;
+  [EVENT_NAMES.CART_VIEWED]: ICartViewed;
+  [EVENT_NAMES.CHECKOUT_CLICKED]: ICheckoutClicked;
+  // add mapping for MY_NEW_EVENT
+  [EVENT_NAMES.MY_NEW_EVENT]: IMyNewEvent
+}
+
+```
+
+5. Follow the step in Releasing a new version of fleek-track-analytic section to release these changes in a new package version
+
+6. Upgrade the package in your application by running
+```sh
+yarn upgrade fleek-track-analytics --latest
+```
+7. Post upgrade the `eventmap` will be updated and available to use (without rebuilding the app if it is already running)
+
+

package/lib/event-map/event-data-types/my-new-event.d.ts

@@ -0,0 +1,4 @@
+export interface IMyNewEvent {
+    prop1: string;
+    prop2: number;
+}

package/lib/event-map/event-data-types/my-new-event.js

@@ -0,0 +1,3 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+//# sourceMappingURL=my-new-event.js.map

package/lib/event-map/event-data-types/my-new-event.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"my-new-event.js","sourceRoot":"","sources":["../../../src/event-map/event-data-types/my-new-event.ts"],"names":[],"mappings":""}

package/lib/event-map/event-map.d.ts

@@ -2,6 +2,7 @@ import { IAddToCart } from './event-data-types/add-to-cart';
 import { ICartViewed } from './event-data-types/cart-viewed';
 import { ICheckoutClicked } from './event-data-types/checkout-clicked';
 import { IHomeScreenViewed } from './event-data-types/home-screen-viewed';
+import { IMyNewEvent } from './event-data-types/my-new-event';
 import { IProductDetailPageViewed } from './event-data-types/product-detail-page-viewed';
 import { IProductTileClicked } from './event-data-types/product-tile-clicked';
 export declare enum EVENT_NAMES {
@@ -10,7 +11,8 @@ export declare enum EVENT_NAMES {
     PRODUCT_DETAIL_PAGE_VIEWED = "product_detail_page_viewed",
     ADD_TO_CART = "add_to_cart",
     CART_VIEWED = "cart_viewed",
-    CHECKOUT_CLICKED = "checkout_clicked"
+    CHECKOUT_CLICKED = "checkout_clicked",
+    MY_NEW_EVENT = "my_new_event"
 }
 export interface EVENT_MAP {
     [EVENT_NAMES.HOME_SCREEN_VIEWED]: IHomeScreenViewed;
@@ -19,4 +21,5 @@ export interface EVENT_MAP {
     [EVENT_NAMES.ADD_TO_CART]: IAddToCart;
     [EVENT_NAMES.CART_VIEWED]: ICartViewed;
     [EVENT_NAMES.CHECKOUT_CLICKED]: ICheckoutClicked;
+    [EVENT_NAMES.MY_NEW_EVENT]: IMyNewEvent;
 }

package/lib/event-map/event-map.js

@@ -9,5 +9,6 @@ var EVENT_NAMES;
     EVENT_NAMES["ADD_TO_CART"] = "add_to_cart";
     EVENT_NAMES["CART_VIEWED"] = "cart_viewed";
     EVENT_NAMES["CHECKOUT_CLICKED"] = "checkout_clicked";
+    EVENT_NAMES["MY_NEW_EVENT"] = "my_new_event";
 })(EVENT_NAMES || (exports.EVENT_NAMES = EVENT_NAMES = {}));
 //# sourceMappingURL=event-map.js.map

package/lib/event-map/event-map.js.map

@@ -1 +1 @@
-{"version":3,"file":"event-map.js","sourceRoot":"","sources":["../../src/event-map/event-map.ts"],"names":[],"mappings":";;;AAOA,IAAY,WAOX;AAPD,WAAY,WAAW;IACrB,uDAAwC,CAAA;IACxC,4DAA6C,CAAA;IAC7C,wEAAyD,CAAA;IACzD,0CAA2B,CAAA;IAC3B,0CAA2B,CAAA;IAC3B,oDAAqC,CAAA;AACvC,CAAC,EAPW,WAAW,2BAAX,WAAW,QAOtB"}
+{"version":3,"file":"event-map.js","sourceRoot":"","sources":["../../src/event-map/event-map.ts"],"names":[],"mappings":";;;AAQA,IAAY,WAQX;AARD,WAAY,WAAW;IACrB,uDAAwC,CAAA;IACxC,4DAA6C,CAAA;IAC7C,wEAAyD,CAAA;IACzD,0CAA2B,CAAA;IAC3B,0CAA2B,CAAA;IAC3B,oDAAqC,CAAA;IACrC,4CAA6B,CAAA;AAC/B,CAAC,EARW,WAAW,2BAAX,WAAW,QAQtB"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "fleek-track-analytics",
-  "version": "0.0.93",
+  "version": "0.0.94",
   "main": "./lib/index.js",
   "types": "./lib/index.d.ts",
   "exports": {