@surveyanalytica/clickstream-rn

SurveyAnalytica Clickstream SDK for React Native. Sends behavioral events from your mobile app to the SA workflow engine.

Installation

npm install @surveyanalytica/clickstream-rn @react-native-async-storage/async-storage

For iOS, install native pods:

cd ios && pod install

@react-native-async-storage/async-storage requires no additional native setup on Android.

Quick Start

1. Initialize in App.js

Call SAClickstream.init() once at app startup, before rendering any screens. It returns a Promise — await it or call it fire-and-forget. Events fired before init resolves are buffered automatically.

// App.js
import { useEffect } from 'react';
import { SAClickstream } from '@surveyanalytica/clickstream-rn';

export default function App() {
  useEffect(() => {
    SAClickstream.init(
      'your-workflow-id',
      'your-api-key',
      { saEndpoint: 'https://api.surveyanalytica.com' }
    );
  }, []);

  return <RootNavigator />;
}

2. Track screen views with useSAPage

Drop useSAPage at the top of any screen component. It fires a page_view event when the screen mounts.

// screens/HomeScreen.js
import { View, Text } from 'react-native';
import { useSAPage } from '@surveyanalytica/clickstream-rn';

export default function HomeScreen() {
  useSAPage('Home');

  return (
    <View>
      <Text>Welcome</Text>
    </View>
  );
}

Pass extra properties as the second argument:

useSAPage('ProductDetail', { productId: '123', category: 'shoes' });

3. Track events

import { SAClickstream } from '@surveyanalytica/clickstream-rn';

// Simple event
SAClickstream.track('button_tapped', { buttonId: 'checkout' });

// With properties
SAClickstream.track('product_viewed', {
  productId: 'abc-123',
  price: 49.99,
  currency: 'USD',
});

4. Identify a user

Call identify() after login to associate the session with a known contact. This emits a uid_transition event and flushes any pending queue.

// After successful login
SAClickstream.identify(user.id);

5. Handle deep link contact IDs

If your app receives a deep link containing ?sa_cid=<id> (e.g. from an SA campaign link), pass the extracted value to init():

import { Linking } from 'react-native';

const url = await Linking.getInitialURL();
const saContactId = url ? new URL(url).searchParams.get('sa_cid') : null;

SAClickstream.init('your-workflow-id', 'your-api-key', {
  saEndpoint: 'https://api.surveyanalytica.com',
  deepLinkContactId: saContactId,
});

When a deepLinkContactId differs from the stored identity, the SDK automatically emits a uid_transition event before switching to the new ID.

6. Consent management

// Revoke consent — stops all tracking and clears the pending queue
SAClickstream.setConsent(false);

// Restore consent — tracking resumes
SAClickstream.setConsent(true);

API Reference

SAClickstream.init(workflowId, apiKey, options) → Promise<void>

| Parameter | Type | Required | Description | |---|---|---|---| | workflowId | string | Yes | SA workflow ID that receives events | | apiKey | string | Yes | Sent as the code request header | | options.saEndpoint | string | Yes | Base URL of the SA backend | | options.deepLinkContactId | string | No | Contact ID from an incoming deep link |

SAClickstream.track(eventName, properties?)

Track a named behavioral event. properties is an arbitrary key/value object.

SAClickstream.page(screenName, properties?)

Track a screen view manually. Prefer useSAPage in screen components.

SAClickstream.identify(contactId)

Link the anonymous visitor to a known contact ID. Emits uid_transition and flushes the queue.

SAClickstream.setConsent(given)

Pass false to stop all tracking. Pass true to resume.

useSAPage(screenName, properties?)

React hook. Calls SAClickstream.page() on mount. Re-fires if screenName changes.

Behavior Details

• Identity: Stored in @react-native-async-storage/async-storage under key sa_id. Generated as a UUID v4 on first launch.
• Batching: Events are batched with a 500 ms debounce, or immediately when 20 events accumulate.
• Retry: Failed requests are retried up to 3 times with exponential backoff (1s, 2s, 4s).
• Device info: Uses Platform.OS from react-native. No react-native-device-info dependency.
• Pre-init buffering: Events fired before init() resolves are buffered in memory and flushed once identity loads.

Peer Dependencies

| Package | Version | |---|---| | react | >=18.0.0 | | react-native | >=0.71.0 | | @react-native-async-storage/async-storage | >=1.18.0 |

License

MIT