@twinalyze/web-analytics

Twinalyze Web Analytics SDK for tracking events, user journeys, sessions, and performance in modern web applications. Automatically capture page views, user interactions, form submissions, and even screen activity to comprehensively understand your website's user experience.

Table of Contents

• Installation
• Quick Start
• Configuration Options
• Tracking Custom Events
• Enhanced Measurement (Auto Tracking)
• Screen Activity Capture

Installation

Install the package via npm, yarn, or using a script tag.

Using npm:

npm install @twinalyze/web-analytics

Using yarn:

yarn add @twinalyze/web-analytics

Using Script Loader (CDN):

<script src="https://cdn.jsdelivr.net/npm/@twinalyze/web-analytics/dist/cdn.global.min.js"></script>

Quick Start

Import the package into your project and initialize it with your unique apiKey and secretKey.

import { TwinalyzeAnalytics } from '@twinalyze/web-analytics';
// If using the CDN script, the SDK is available via window.twinalyze or window.TwinalyzeAnalytics

TwinalyzeAnalytics.init({ 
  apiKey: 'YOUR_API_KEY', 
  secretKey: 'YOUR_SECRET_KEY' 
});

Once initialized, the SDK will automatically begin tracking page views, sessions, and basic user interactions based on its default enhanced measurement configuration.

Configuration Options

You can customize the behavior of the SDK by passing an options object to the init() method.

| Option | Type | Default | Description | |--------|------|---------|-------------| | apiKey | String | Required | Your Twinalyze API Key. | | secretKey | String | Required | Your Twinalyze Secret Key (used for request signing). | | socketUrl | String | "https://api.twinalyze.com" | Base URL for the analytics socket connection. | | persistSession | Boolean | true | Whether to persist the session ID in sessionStorage. | | encrypt | Boolean | true | Enables AES encryption for data payloads sent to the server. | | debug | Boolean | true | Outputs tracking and SDK events to the console for debugging. | | enhancedMeasurement | Object | See below | Fine-tune auto-tracked events like clicks and scrolls. | | screenActivity | Object | See below | Configuration for automated screen captures. |

Example Full Configuration

TwinalyzeAnalytics.init({
  apiKey: 'YOUR_API_KEY',
  secretKey: 'YOUR_SECRET_KEY',
  socketUrl: 'https://api.twinalyze.com',
  persistSession: true,
  enhancedMeasurement: {
    pageViews: true,
    scrolls: true,
    outboundClicks: true,
    formInteractions: true,
    siteSearch: { params: ["q", "s", "search", "query"] },
    fileDownloads: { extensions: ["pdf", "zip", "doc", "xls"] }
  },
  screenActivity: {
    enabled: false, // Can be dynamically enabled by the server
    throttleMs: 2000,
    jpegQuality: 0.7,
    capture: "viewport"
  }
});

Tracking Custom Events

To capture specific actions in the user journey, you can track custom events manually. You can pass an optional object containing properties relevant to the event.

TwinalyzeAnalytics.track('purchase_completed', {
  transaction_id: 'T12345',
  value: 299.99,
  currency: 'USD',
  items_count: 3
});

All custom events automatically inherit contextual properties such as page_url, page_title, and device_type.

Enhanced Measurement (Auto Tracking)

By default, the SDK automatically tracks several key user interactions without requiring manual instrumentation. You can disable or configure these via the enhancedMeasurement initialization parameter.

1. Page Views (page_view):
   • Tracks initial page loads and history state changes (ideal for SPAs like React, Vue, Angular).
2. Scrolls (scroll):
   • Fires when the user scrolls down to 90% of the page height.
3. Clicks (click):
   • Captures interactions with links, buttons, and dropdowns.
   • Automatically detects outbound links and logs the link_url, button_type, and the visible text (element_text) of the clicked element.
4. Site Search (view_search_results):
   • Triggers when the URL contains specific query parameters (e.g., ?q=shoes).
5. Form Interactions (form_start, form_submit):
   • Tracks when a user first interacts with a form (form_start) and when they submit it (form_submit), logging the form's id and action.
6. File Downloads (file_download):
   • Fires when a user clicks a link ending in common file extensions (like .pdf, .zip, .docx).

Screen Activity Capture

The SDK supports capturing a visual snapshot of the user's screen during key interactions to provide deep insights into the user journey.

• By default, screen capture is securely controlled and can be dynamically enabled by the server (debugScreenshotCapture).
• Captures are throttled (default 2000ms) to optimize performance.
• Only the visible viewport is captured by default to reduce payload size.

If enabled, screenshots are automatically attached to key events like click, page_view, and form_submit.