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 setup for development
• How to change event map
• How to publish changes to npm

How to Integrate

1. Install the package

# npm
npm install fleek-track-analytics

# yarn
yarn add fleek-track-analytics

2. Import based on platform

# 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.

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();

export { analyticsWrapper }

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

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

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

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

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

// 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

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

  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

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)