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

• fleek-track-analytics
  • Table of Contents
• How to Integrate
• How to setup for development
• How to publish changes to npm
• How to change event map

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 | | rudderstack | object (optional) | RudderStack configuration for self-hosted migration (see RudderStack Setup below) |

RudderStack Setup (Self-Hosted Migration)

This library supports dual-sending events to both Segment and RudderStack for gradual migration. RudderStack integration is currently available for Web platform only (PoC phase).

Configuration

To enable RudderStack, add the rudderstack configuration to your TrackAnalytics initialization:

const analyticsWrapper = new TrackAnalytics({
  platform: 'WEB',
  App: 'CONSUMER_WEB',
  segment: true,
  segmentKey: process.env.SEGMENT_KEY || '',
  rudderstack: {
    enabled: true,
    writeKey: process.env.RUDDERSTACK_WRITE_KEY || '',
    dataPlaneUrl: process.env.RUDDERSTACK_DATA_PLANE_URL || '', // e.g., 'https://dataplane.yourdomain.com'
  },
  errorHandler: analyticsException,
});

Event Routing

Event routing to RudderStack is controlled by an internal library configuration file (src/web/analytics-tool/rudderstack-event-routing.ts). This allows you to selectively send specific events to RudderStack during the PoC phase without requiring application changes.

Important:

• All events are always sent to Segment (unchanged behavior)
• Events are conditionally sent to RudderStack based on the internal routing configuration
• RudderStack failures do not affect Segment sending

How It Works

1. Dual-Send Architecture: Events are sent to both Segment and RudderStack (when configured)
2. Internal Routing Config: Modify src/web/analytics-tool/rudderstack-event-routing.ts in this repository to control which events are sent to RudderStack
3. Fail-Safe: If RudderStack initialization or sending fails, the library continues with Segment only

Event Routing Configuration

To control which events are sent to RudderStack, modify the rudderstackEventRouting object in src/web/analytics-tool/rudderstack-event-routing.ts:

export const rudderstackEventRouting: IRudderstackEventRouting = {
  // Option 1: List specific event names
  sendToRudderstack: [
    'event_name_1',
    'event_name_2',
  ],
  
  // Option 2: Use regex patterns
  eventPatterns: ['^test_', '^poc_'], // Matches events starting with 'test_' or 'poc_'
};

Requirements

• Data Plane URL: Your self-hosted RudderStack data plane endpoint
• Write Key: Source write key from RudderStack control plane
• Self-Hosted Setup: See spec-files/rudderstack-migration/RUDDERSTACK_SELF_HOSTED_PARAMETERS.md for detailed setup instructions

Documentation

For more details on the migration, see:

• SDK Comparison: spec-files/rudderstack-migration/SEGMENT_VS_RUDDERSTACK_SDK_COMPARISON.md
• Self-Hosted Parameters: spec-files/rudderstack-migration/RUDDERSTACK_SELF_HOSTED_PARAMETERS.md
• Architecture (HLD/LLD): spec-files/rudderstack-migration/HLD_LLD.md

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)
8. After adding an event here, you also need to update the mapping on Segment website