fleek-track-analytics

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

1. 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";

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

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

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

1. 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
}

1. 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  
}

1. 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
}

1. Follow the step in Releasing a new version of fleek-track-analytic section to release these changes in a new package version

2. Upgrade the package in your application by running

yarn upgrade fleek-track-analytics --latest

1. Post upgrade the eventmap will be updated and available to use (without rebuilding the app if it is already running)