uengage-react-native-funnel-tracker-sdk

A lightweight event tracking SDK for React Native apps, used to send batched funnel events to the Uengage funnel tracking backend.

• 📦 Built for React Native >=0.68.3
• ⚛️ React 17 compatible
• 💾 Uses @react-native-community/async-storage for persistent visitor_id
• 📡 Batches events and flushes periodically + when app goes to background

1. Installation

Peer dependencies

Your React Native app must already have:

"dependencies": {
  "react": "17.0.2",
  "react-native": "0.68.3",
  "@react-native-community/async-storage": "^1.12.1"
}

Versions in other apps just need to satisfy:

• react: >=17.0.0 <18.0.0
• react-native: >=0.64.0 <0.71.0
• @react-native-community/async-storage: >=1.12.1 <2.0.0

Install the SDK

npm install uengage-react-native-funnel-tracker-sdk
# or
yarn add uengage-react-native-funnel-tracker-sdk

2. Quick Start

Initialize the tracker once (usually at app startup) and then call trackEvent wherever you need.

// App.tsx
import React, { useEffect } from "react";
import { View, Text } from "react-native";
import {
  initTracker,
  trackEvent
} from "uengage-react-native-funnel-tracker-sdk";

const App = () => {
  useEffect(() => {
    initTracker({
      batchSize: 10,
      flushInterval: 5000,
      platform: "application",
      tenantToken: "<TENANT_TOKEN_FROM_BACKEND>"
    });

    // Example event
    trackEvent("app_open");
  }, []);

  return (
    <View>
      <Text>Hello Funnel Tracker</Text>
    </View>
  );
};

export default App;

3. Configuration

initTracker(config)

Call once at app startup (e.g. in App.tsx or in your root provider file).

initTracker({
  batchSize: number;      // optional - default: 10
  flushInterval: number;  // optional - ms, default: 5000 (5s)
  platform: string;       // optional - default: "application"
  tenantToken: string | null; // required in production
});

Example

initTracker({
  batchSize: 20,
  flushInterval: 7000,
  platform: "android",
  tenantToken: "tenant_abc_123"
});

Note: If tenantToken is missing, the SDK will log a warning but still try to send events.

4. Tracking Events

trackEvent(eventName, options?)

Tracks a single event and pushes it into a local queue.

When the queue size reaches batchSize or when the flush interval fires, events are sent in a batch to your backend.

trackEvent(eventName: string, options?: {
  userId?: string | null;
  metadata?: Record<string, any>;
}): Promise<void>

Basic example

trackEvent("app_open");

With userId and metadata

trackEvent("order_created", {
  userId: "user_123",
  metadata: {
    orderId: "ORD-9876",
    amount: 499,
    currency: "INR"
  }
});

5. How events are structured

Each event sent to the backend looks like:

{
  "event": "order_created",
  "visitor_id": "v_xxxxx",          // stored in AsyncStorage
  "user_id": "user_123",            // from options.userId
  "url": null,                      // not applicable in React Native
  "captured_at": "2025-11-17 12:34:56", // IST (Asia/Kolkata)
  "platform": "application",             // from config.platform
  "system": "android",              // Platform.OS
  "metadata": { /* custom data */ }
}

The full request body sent to the server:

{
  "tenantToken": "tenant_abc_123",
  "events": [ /* array of event objects */ ]
}

6. Visitor ID

The SDK generates a persistent visitor_id and stores it using @react-native-community/async-storage.

• Key: uengage_visitor_id
• Format: "v_" + random + timestamp

You can access it if needed:

getVisitorId()

import { getVisitorId } from "uengage-react-native-funnel-tracker-sdk";

const visitorId = await getVisitorId();
console.log("Visitor ID:", visitorId);

7. Flushing events

Events are flushed automatically when:

1. The in-memory queue length reaches batchSize
2. The flush timer ticks (flushInterval in ms)
3. The app goes to background (AppState changes from active to background/inactive)

You can also trigger manual flush:

flushEvents()

import { flushEvents } from "uengage-react-native-funnel-tracker-sdk";

await flushEvents();

8. Shutdown / cleanup (optional)

If you need to clean up listeners and timers (e.g. during tests):

shutdownTracker()

import { shutdownTracker } from "uengage-react-native-funnel-tracker-sdk";

shutdownTracker();

This:

• Clears the internal interval timer
• Unsubscribes from AppState changes

9. TypeScript support

The SDK is written in TypeScript and ships type declarations.

You get full typings out of the box:

import {
  initTracker,
  trackEvent,
  flushEvents,
  getVisitorId,
  shutdownTracker,
  type TrackerConfig,
  type TrackEventOptions
} from "uengage-react-native-funnel-tracker-sdk";

Example of using TrackerConfig in your own abstraction:

import type { TrackerConfig } from "uengage-react-native-funnel-tracker-sdk";

const config: Partial<TrackerConfig> = {
  tenantToken: "tenant_abc_123"
};

10. Notes & Gotchas

• Call initTracker before trackEvent If you forget, the SDK will log a warning and ignore the event.

• No window.location This is React Native, so url is always null. If you want to track screens, pass them in metadata:

  trackEvent("screen_view", {
    metadata: {
      screen: "HomeScreen"
    }
  });

• Time zone is IST (Asia/Kolkata) captured_at is formatted as YYYY-MM-DD HH:mm:ss in IST.

• Offline handling Currently, events are queued in memory and retried on flush failure by re-adding them to the queue. For full offline durability, additional storage logic can be added in a future version.

11. Example: Screen tracking helper

Here’s a small example you can add in your app (not part of the SDK):

// trackerHelpers.ts
import { trackEvent } from "uengage-react-native-funnel-tracker-sdk";

export function trackScreenView(screenName: string, userId?: string) {
  return trackEvent("screen_view", {
    userId,
    metadata: { screen: screenName }
  });
}

And use with React Navigation:

// Somewhere in your navigation container
trackScreenView("HomeScreen", currentUserId);