securoanalytics-sdk

A lightweight browser SDK for Securo Analytics tracking.

Installation

npm install securoanalytics-sdk

Quick Start

import Analytics from 'securoanalytics-sdk';

Analytics.init({
  apiKey: 'PROJECT_API_KEY'
});

Analytics.trackPageView();
Analytics.trackEvent('button_click', { button: 'signup' });

SDK Overview

The SDK provides a small browser client that automatically builds tracking payloads and sends them to your Securo Analytics backend.

Supported APIs:

• Analytics.init(options)
• Analytics.trackPageView(custom)
• Analytics.trackRoute(route)
• Analytics.trackEvent(eventName, eventData)
• Analytics.trackPurchase(data)
• Analytics.trackSignup(data)
• Analytics.trackLogin(data)

Initialization Options

Analytics.init(options)

The init() method must be called before the tracker can send events.

Supported options:

• apiKey (string, required)
  • Your project API key.
• sessionId (string, optional)
  • Custom session identifier.
  • If omitted, the SDK generates a session ID automatically.
• visitorId (string, optional)
  • Custom visitor identifier.
  • If omitted, the SDK creates or reuses a browser-local visitor token.
• routeTracking (boolean, optional)
  • Enables automatic route tracking.
  • Default: true.
  • Set to false to disable automatic page/route tracking if you want to manage pageviews manually.

Example:

Analytics.init({
  apiKey: 'PROJECT_API_KEY',
  visitorId: 'user-123',
  sessionId: 'session-abc',
  routeTracking: false
});

Backend API Configuration

By default, the SDK sends requests to http://localhost:5000/api.

To override the endpoint, set the global variable before loading the SDK:

window.__ANALYTICS_API_URL__ = 'https://analytics.example.com/api';

Tracking Methods

Analytics.trackPageView(custom)

Send a page view event to the backend.

The SDK automatically sends these fields:

• apiKey
• sessionId
• visitorId
• route (current window.location.pathname unless overridden)
• referrer (document.referrer)
• language (navigator.language)
• screenResolution (width x height)
• device (navigator.userAgent)
• browser (navigator.userAgent)
• os (navigator.platform)

You can override or add additional fields by passing custom:

Analytics.trackPageView({
  route: '/dashboard',
  referrer: 'https://example.com',
  extraInfo: 'test'
});

Analytics.trackRoute(route)

Alias for tracking a route change.

Analytics.trackRoute('/settings');

Analytics.trackEvent(eventName, eventData = {})

Send a custom event.

eventName is the event label, and eventData can include any additional payload fields.

Example:

Analytics.trackEvent('button_click', {
  button: 'signup',
  campaign: 'spring_sale'
});

The request includes:

• apiKey
• sessionId
• visitorId
• eventName
• eventData (nested object)
• route
• plus each key from eventData spread to the top level

Analytics.trackPurchase(data = {})

Helper for purchase events.

Analytics.trackPurchase({
  orderId: 'ORD123',
  value: 99.95,
  currency: 'USD'
});

Analytics.trackSignup(data = {})

Helper for signup events.

Analytics.trackSignup({
  plan: 'pro'
});

Analytics.trackLogin(data = {})

Helper for login events.

Analytics.trackLogin({
  method: 'google'
});

Automatic Route Tracking

When routeTracking is enabled, the SDK listens for:

• window.load
• browser history popstate
• history.pushState

It sends a page view automatically when the user navigates inside a single-page application.

Recommended Usage

import Analytics from 'securoanalytics-sdk';

window.__ANALYTICS_API_URL__ = 'https://analytics.example.com/api';

Analytics.init({
  apiKey: 'PROJECT_API_KEY'
});

// Page view when app loads or route changes
Analytics.trackPageView();

// Track custom events
Analytics.trackEvent('newsletter_signup', { source: 'footer' });
Analytics.trackPurchase({ orderId: '1234', amount: 49.99 });

Notes

• The SDK is intended for browser use.
• Keep apiKey private for each project.
• If you disable automatic route tracking, you must call trackPageView() or trackRoute() manually.