This guide covers installing and using the SurveyAnalytica Clickstream SDK on web projects. The SDK is published to npm and works in any JavaScript environment including Vanilla JS, Next.js, and React. For mobile apps, see the Mobile SDKs guide.

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

Installation

Vanilla JS / HTML sites

Include the UMD bundle directly in your page. No build step required.

<script src="https://cdn.jsdelivr.net/npm/@surveyanalytica/clickstream-web/dist/index.umd.js"></script>
<script>
  SAClickstream.init('YOUR_WORKFLOW_ID', 'YOUR_API_KEY', {
    endpoint: 'YOUR_ENDPOINT_URL'
  });
</script>

npm projects (Next.js, React, etc.)

npm install @surveyanalytica/clickstream-web

Then initialise once, at the entry point of your app:

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

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

For Next.js, call init inside a Client Component or in _app.js / layout.js. The SDK is server-side rendering safe — all browser API access is guarded internally.

Tracking page views

The SDK tracks page views automatically. Every time the URL changes (including single-page navigation via the History API), a page_view event is sent with the current URL, page title, and referrer. No code is needed beyond the init call.

To send a page view manually:

SAClickstream.page('/checkout', { campaign: 'summer-sale' });

Tracking custom events

SAClickstream.track('button_clicked', {
  label: 'Buy Now',
  productId: 'sku-9821',
  price: 49.99
});

Property values can be strings, numbers, booleans, or nested objects. Keep event names short and consistent across your codebase (for example, always use button_clicked rather than mixing buttonClick and btn_tap).

Identifying users after login

Before login, the SDK assigns each visitor a random anonymous ID stored in localStorage. After login, call identify with the contact ID from your backend:

// After a successful login
SAClickstream.identify('contact-id-from-your-backend');

This sends a uid_transition event linking the anonymous session to the known contact. Events recorded before login are associated with the contact via the anonymous ID stored on the contact record — no data is lost.

Consent management

If your site uses a cookie consent banner, respect the user’s choice:

// User accepted tracking
SAClickstream.setConsent(true);

// User declined tracking
SAClickstream.setConsent(false);

When consent is set to false, tracking stops immediately and the anonymous ID association is cleared. No further events are sent until consent is re-granted.

How events are sent

The SDK batches events and sends them every 500 milliseconds, or immediately when 20 events have queued. Failed requests are retried up to three times with increasing delays. This keeps network usage low without losing events during temporary connectivity issues.

Troubleshooting

Events are not appearing in my workflow

• Confirm the workflow is in Active state.
• Check the browser console for any network errors on requests to your endpoint URL.
• Verify the API Key matches the KEY shown in the trigger drawer — copy and paste rather than typing.
• Ensure init is called before any track or page calls.

Duplicate page views are being recorded

If you call SAClickstream.page() manually in addition to the automatic tracking, you will see two events per navigation. Either disable automatic tracking (autoPage: false in the init options) or remove your manual page() calls.