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.
npm install fleek-track-analyticsfleek-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.
- 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
---
1. Install the package
``shnpm
npm install 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();
export { analyticsWrapper }
`Parameter description for TrackAnalytics class constructor
| property | value | description |
| ------------- |:-------------:| ----- |
| platfrom |
, 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).
$3
To enable RudderStack, add the
rudderstack configuration to your TrackAnalytics initialization:`ts
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,
});
`$3
Event routing to RudderStack is controlled by an internal library configuration file (
). 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
$3
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$3
To control which events are sent to RudderStack, modify the
rudderstackEventRouting object in src/web/analytics-tool/rudderstack-event-routing.ts:`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_'
};
`$3
- Data Plane URL: Your self-hosted RudderStack data plane endpoint
- Write Key: Source write key from RudderStack control plane
- Self-Hosted Setup: See
for detailed setup instructions$3
For more details on the migration, see:
- SDK Comparison:
spec-files/rudderstack-migration/SEGMENT_VS_RUDDERSTACK_SDK_COMPARISON.md
- Self-Hosted Parameters:
- Architecture (HLD/LLD): 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
. 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
`tsanalytics.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
to 1.2.20
- If changes in eventmap upgrade as patch. Example to 1.2.212. Build and publish
sh
yarn build && npm publish
How to update event map
In order to build reliability in event data consistency across platform,
function expets event name and event properties to be type defined before use. The function defination for track is hence,`ts
type track = (eventName: T, eventParams: EVENT_MAP[T]) => Promise | 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
ts
// src/event-map/event-map.tsexport 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
ts
src/event-map/event-data-types/my-new-event.tsexport interface IMyNewEvent {
id: string;
city: string,
prop1: number,
prop2: boolean
}
`4. Add the mapping of event name and params in
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