Skip to content
Segmentify React Native SDK Docs

End-to-End Implementation

For developers

The complete zero-to-production integration path. For the conceptual model behind these steps, see How Tracking Works.

Goal

This guide is the complete implementation path for teams that want to integrate the SDK from zero to production with clear event coverage.

Source of truth in this repository:

  • Runtime implementation: src/classes/events.ts
  • Type contracts: src/types.ts
  • Initialization bootstrap: src/classes/initialize.ts
  • Example app integration: example/src/App.tsx (Event Playground with inspector; swap in your root and navigation as in step 4 above)

1) Install and prepare project

Install and verify dependencies in your app workspace:

Terminal window
pnpm add @segmentify/react-native-v2

If you are using Expo, ensure Expo core modules resolve correctly in the app package:

Terminal window
pnpm add expo expo-modules-core

2) Define SDK configuration

Create config similar to shared/segmentify-configuration.ts:

  • config.segmentifyApiUrl
  • config.segmentifyPushUrl
  • config.apiKey
  • config.domain
  • config.language
  • config.currency
  • config.testMode
  • pageTypeMapping

Keep route keys in pageTypeMapping synchronized with your real navigation route names.

3) Initialize SDK once

Initialize once at app startup:

import { Initialize } from '@segmentify/react-native-v2';


const segmentify = new Initialize(SEGMENTIFY_CONFIGURATION);

What Initialize does internally

In src/classes/initialize.ts, the constructor starts async bootstrap work:

  1. Stores loggerOptions and config in SDK storage.
  2. Collects and stores device information.
  3. Stores testMode state.
  4. Creates Events and ensures sessionId + userId via getOrSetUserSessionId().
  5. Prepares navigation tracking bridge (navigationObserver).

If bootstrap fails, SDK logs a warning but does not crash the app.

Step-by-step implementation

1) Build configuration object

Create a config object like shared/segmentify-configuration.ts:

  • pageTypeMapping
  • loggerOptions
  • config

Example:

const SEGMENTIFY_CONFIGURATION = {
  pageTypeMapping: {
    Home: 'Home Page',
    Product: 'Product Page',
    Basket: 'Basket Page',
  },
  loggerOptions: {
    debugMode: true,
  },
  config: {
    segmentifyApiUrl: 'https://per2.segmentify.com',
    segmentifyPushUrl: 'https://psh2.segmentify.com',
    domain: 'your-domain.com',
    apiKey: 'your-api-key',
    language: 'EN',
    currency: 'EUR',
    testMode: false,
  },
};

4) Connect navigation tracking

Attach navigationObserver to your app NavigationContainer and trigger the first page hit:

<NavigationContainer onStateChange={segmentify.navigationObserver}>
segmentify.triggerInitialPageView('Home');

This ensures first page and route transitions both produce PAGE_VIEW.

5) Create one shared Events instance

import { Events } from '@segmentify/react-native-v2';


const events = new Events();

Use this instance in hooks/screens/services to send business actions.

6) Implement core commerce events

Implement in this order:

  1. ProductView on product detail display
  2. BasketAdd / BasketRemove on cart mutations
  3. BasketView when basket page opens
  4. Purchase on successful checkout completion

Example:

await events.ProductView({
  productId: product.id,
  title: product.title,
  price: product.price,
  category: product.category,
});


await events.BasketAdd({
  productId: product.id,
  quantity: 1,
  price: product.price,
});

7) Implement identity lifecycle

Send user lifecycle events after successful backend operations:

  • Register after signup success
  • Login after sign-in success
  • Logout on signout flow
  • Identify when user profile/preferences change

Example:

await events.Register({
  email: form.email,
  externalId: form.userId,
  emailNtf: true,
});

8) Implement search and interaction

Search event modes in this SDK:

  • Before Search: query: '', type: 'instant'
  • After Search: query non-empty, type: 'instant'
  • Searchandising: query non-empty, type: 'faceted'

UI engagement:

  • Interaction for click/impression/widget actions
  • Form for form submission events

The Event Playground in example/src/App.tsx wires concrete Search and Interaction samples you can copy; see Search, Interaction, Form and Custom.

9) Implement push events

Push events use static methods in Events:

  • Events.subscribePushNotification({ token, providerType?: 'FIREBASE' | 'APNS' })
  • Events.pushNotificationInteraction({ type: 'VIEW' | 'CLICK', instanceId })

Recommended flow:

  1. Request notification permission
  2. Retrieve device token
  3. Subscribe push token
  4. Send interaction events on receive/open callbacks

10) Understand auto-enriched fields

sendEvent() automatically extends outgoing payload with:

  • userId
  • sessionId
  • device
  • os
  • osversion
  • currency
  • lang
  • testMode
  • email (if user exists in SDK storage)

You usually send only business parameters; SDK enrichment handles context fields.

11) Queue behavior and reliability

The SDK has queue logic:

  • If nextPage: true, payload is queued in SEGMENTIFY_EVENT_QUEUE.
  • Offline logic can also queue payloads.
  • Once online, queued events replay through sendEvent().

This reduces event loss during temporary connectivity issues.

12) Production checklist

  • Initialize SDK exactly once.
  • Wire navigationObserver and triggerInitialPageView.
  • Send events from deterministic business actions (not uncontrolled renders).
  • Ensure Purchase is sent once per order confirmation.
  • Keep identity events aligned with auth/backend success.
  • Test with unstable network to verify queue replay.
  • Enable debug logs in non-production environments.

13) Validation strategy

For each flow, validate:

  • Request payload shape (business fields + enriched fields)
  • Correct event name and step
  • Correct userId and sessionId continuity
  • No duplicates for lifecycle-critical events (Purchase, Register, Login)

You can use the sample event inspector panel in example/src/App.tsx during development.

Next reading