This guide covers installing and using the SurveyAnalytica Clickstream SDK on mobile platforms: React Native, Flutter, iOS (Swift), and Android (Kotlin). For web projects, see the Web SDK guide.

Before you start, complete the workflow setup to get your API Key and Endpoint URL.

React Native

Installation

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

Initialise

Call init once when your app starts, before any navigation renders:

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

await SAClickstream.init('YOUR_WORKFLOW_ID', 'YOUR_API_KEY', {
  endpoint: 'YOUR_ENDPOINT_URL'
});

Track screens and events

// Screen view (call from useEffect in each screen component)
SAClickstream.page('ProductDetailScreen');

// Custom event
SAClickstream.track('add_to_cart', { productId: 'sku-9821', quantity: 2 });

// Identify after login
SAClickstream.identify('contact-id-from-your-backend');

// Revoke consent
SAClickstream.setConsent(false);

---

Flutter

Installation

flutter pub add sa_clickstream

Initialise

Call initialize in main() before runApp:

import 'package:sa_clickstream/sa_clickstream.dart';

void main() async {
  WidgetsFlutterBinding.ensureInitialized();
  await SAClickstream.initialize(
    workflowId: 'YOUR_WORKFLOW_ID',
    apiKey: 'YOUR_API_KEY',
    saEndpoint: 'YOUR_ENDPOINT_URL',
  );
  runApp(const MyApp());
}

Automatic screen tracking

Add SARouteObserver to your MaterialApp to track screen transitions automatically:

MaterialApp(
  navigatorObservers: [SARouteObserver()],
  ...
)

Track events and identify users

SAClickstream.track('button_tapped', properties: {'label': 'Buy Now'});
SAClickstream.page('CheckoutScreen');
SAClickstream.identify('contact-id-from-your-backend');
SAClickstream.setConsent(false);

---

iOS (Swift)

Installation

Swift Package Manager — in Xcode go to File → Add Package Dependencies and enter:

https://github.com/aphougat/clickstream-ios

Select version 1.0.0 or later.

CocoaPods — add to your Podfile:

pod 'SAClickstream', '~> 1.0'

Then run pod install.

Initialise

Call initialize in your AppDelegate or @main struct before the first scene appears:

import SAClickstream

SAClickstream.initialize(
    workflowId: "YOUR_WORKFLOW_ID",
    apiKey: "YOUR_API_KEY",
    saEndpoint: "YOUR_ENDPOINT_URL"
)

Track screens and events

// In viewDidAppear
SAClickstream.page("ProductDetailViewController")

// Custom event
SAClickstream.track("button_tapped", properties: ["label": "Buy Now"])

// Identify after login
SAClickstream.identify("contact-id-from-your-backend")

// Revoke consent
SAClickstream.setConsent(false)

---

Android (Kotlin)

Installation

Add the GitHub Packages repository and dependency to your build.gradle.kts:

repositories {
    maven {
        url = uri("https://maven.pkg.github.com/aphougat/clickstream-android")
        credentials {
            username = providers.gradleProperty("gpr.user").orElse("").get()
            password = providers.gradleProperty("gpr.token").orElse("").get()
        }
    }
}

dependencies {
    implementation("com.surveyanalytica:clickstream-android:1.0.0")
}

Initialise

Call initialize in your Application.onCreate():

import com.surveyanalytica.clickstream.SAClickstream

class MyApplication : Application() {
    override fun onCreate() {
        super.onCreate()
        SAClickstream.initialize(
            context = this,
            workflowId = "YOUR_WORKFLOW_ID",
            apiKey = "YOUR_API_KEY",
            saEndpoint = "YOUR_ENDPOINT_URL"
        )
    }
}

Track screens and events

// In Activity.onResume or Fragment.onResume
SAClickstream.page("ProductDetailActivity")

// Custom event
SAClickstream.track("button_tapped", mapOf("label" to "Buy Now"))

// Identify after login
SAClickstream.identify("contact-id-from-your-backend")

// Revoke consent
SAClickstream.setConsent(false)

How events are sent (all platforms)

On all platforms the SDK works the same way: events are queued locally and flushed every 500 milliseconds, or immediately when 20 events have accumulated. Each flush sends a single batch request. Failed requests are retried up to three times with increasing delays. The anonymous identity assigned at first launch is persisted across sessions so users are consistently identified until you call identify.

Troubleshooting

Events are not appearing in my workflow

• Confirm the workflow is in Active state in SurveyAnalytica.
• Check your device or simulator logs for any network errors.
• Verify the API Key matches the KEY in the trigger drawer exactly.
• Ensure initialize / init is called before any tracking calls.

Android: dependency not found

The Android SDK is distributed via GitHub Packages. Make sure your gradle.properties or CI environment includes a valid gpr.user and gpr.token (a GitHub personal access token with read:packages permission).