@twinalyze/web-analytics 1.0.14 → 1.0.15

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (8) hide show
  1. package/README.md +131 -18
  2. package/dist/cdn.global.min.js +5 -4
  3. package/dist/cdn.global.min.js.map +1 -1
  4. package/dist/index.js +3 -2
  5. package/dist/index.js.map +1 -1
  6. package/dist/index.mjs +3 -2
  7. package/dist/index.mjs.map +1 -1
  8. package/package.json +1 -2
package/README.md CHANGED
@@ -1,35 +1,148 @@
1
- <img src="https://twinnettechnologies.com/twinalyze.com/assets/main-logo.png" alt="Twinalyze Logo" width="200"/>
1
+ <p align="center">
2
+ <img src="https://twinnettechnologies.com/twinalyze.com/assets/main-logo.png" alt="Twinalyze Logo" width="200"/>
3
+ </p>
2
4
 
3
5
  # @twinalyze/web-analytics
4
6
 
5
- **Twinalyze Web Analytics SDK** for tracking events, sessions, users, and performance in modern web applications.
7
+ **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.
6
8
 
7
- ## Installation and Quick Start
8
- To get started with using Twinalyze Web SDK, install the package to your project via npm, yarn or script loader.
9
+ ---
9
10
 
10
- **Using npm CLI:**
11
+ ## Table of Contents
12
+
13
+ - [Installation](#installation)
14
+ - [Quick Start](#quick-start)
15
+ - [Configuration Options](#configuration-options)
16
+ - [Tracking Custom Events](#tracking-custom-events)
17
+ - [Enhanced Measurement (Auto Tracking)](#enhanced-measurement-auto-tracking)
18
+ - [Screen Activity Capture](#screen-activity-capture)
19
+
20
+ ---
21
+
22
+ ## Installation
23
+
24
+ Install the package via npm, yarn, or using a script tag.
25
+
26
+ **Using npm:**
11
27
  ```bash
12
28
  npm install @twinalyze/web-analytics
13
29
  ```
14
- <!-- **Using yarn CLI:**
30
+
31
+ **Using yarn:**
15
32
  ```bash
16
33
  yarn add @twinalyze/web-analytics
17
- ``` -->
34
+ ```
18
35
 
19
- Import the package into your project and initialize it with your API key.
20
- ```bash
36
+ **Using Script Loader (CDN):**
37
+ ```html
38
+ <script src="https://cdn.jsdelivr.net/npm/@twinalyze/web-analytics/dist/cdn.global.min.js"></script>
39
+ ```
40
+
41
+ ---
42
+
43
+ ## Quick Start
44
+
45
+ Import the package into your project and initialize it with your unique `apiKey` and `secretKey`.
46
+
47
+ ```javascript
21
48
  import { TwinalyzeAnalytics } from '@twinalyze/web-analytics';
49
+ // If using the CDN script, the SDK is available via window.twinalyze or window.TwinalyzeAnalytics
22
50
 
23
- TwinalyzeAnalytics.init({ apiKey: 'YOUR_API_KEY' , organization: 'YOUR_ORG_ID' });
51
+ TwinalyzeAnalytics.init({
52
+ apiKey: 'YOUR_API_KEY',
53
+ secretKey: 'YOUR_SECRET_KEY'
54
+ });
24
55
  ```
25
56
 
26
- Installing via script loader
27
- ```bash
28
- <script src="https://cdn.jsdelivr.net/npm/@twinalyze/web-analytics/dist/cdn.global.min.js"></script>
57
+ Once initialized, the SDK will automatically begin tracking page views, sessions, and basic user interactions based on its default enhanced measurement configuration.
58
+
59
+ ---
60
+
61
+ ## Configuration Options
62
+
63
+ You can customize the behavior of the SDK by passing an options object to the `init()` method.
64
+
65
+ | Option | Type | Default | Description |
66
+ |--------|------|---------|-------------|
67
+ | `apiKey` | `String` | **Required** | Your Twinalyze API Key. |
68
+ | `secretKey` | `String` | **Required** | Your Twinalyze Secret Key (used for request signing). |
69
+ | `socketUrl` | `String` | `"https://api.twinalyze.com"` | Base URL for the analytics socket connection. |
70
+ | `persistSession` | `Boolean` | `true` | Whether to persist the session ID in `sessionStorage`. |
71
+ | `encrypt` | `Boolean` | `true` | Enables AES encryption for data payloads sent to the server. |
72
+ | `debug` | `Boolean` | `true` | Outputs tracking and SDK events to the console for debugging. |
73
+ | `enhancedMeasurement` | `Object` | See below | Fine-tune auto-tracked events like clicks and scrolls. |
74
+ | `screenActivity` | `Object` | See below | Configuration for automated screen captures. |
75
+
76
+ ### Example Full Configuration
77
+
78
+ ```javascript
79
+ TwinalyzeAnalytics.init({
80
+ apiKey: 'YOUR_API_KEY',
81
+ secretKey: 'YOUR_SECRET_KEY',
82
+ socketUrl: 'https://api.twinalyze.com',
83
+ persistSession: true,
84
+ enhancedMeasurement: {
85
+ pageViews: true,
86
+ scrolls: true,
87
+ outboundClicks: true,
88
+ formInteractions: true,
89
+ siteSearch: { params: ["q", "s", "search", "query"] },
90
+ fileDownloads: { extensions: ["pdf", "zip", "doc", "xls"] }
91
+ },
92
+ screenActivity: {
93
+ enabled: false, // Can be dynamically enabled by the server
94
+ throttleMs: 2000,
95
+ jpegQuality: 0.7,
96
+ capture: "viewport"
97
+ }
98
+ });
29
99
  ```
30
100
 
31
- ## Tracking events
32
- Once the SDK is initialize, you can start tracking events.
33
- ```bash
34
- TwinalyzeAnalytics.track('Custom_Event_Name', { label: 'Event Label' , value: 100 })
35
- ```
101
+ ---
102
+
103
+ ## Tracking Custom Events
104
+
105
+ 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.
106
+
107
+ ```javascript
108
+ TwinalyzeAnalytics.track('purchase_completed', {
109
+ transaction_id: 'T12345',
110
+ value: 299.99,
111
+ currency: 'USD',
112
+ items_count: 3
113
+ });
114
+ ```
115
+
116
+ All custom events automatically inherit contextual properties such as `page_url`, `page_title`, and `device_type`.
117
+
118
+ ---
119
+
120
+ ## Enhanced Measurement (Auto Tracking)
121
+
122
+ 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.
123
+
124
+ 1. **Page Views (`page_view`)**:
125
+ - Tracks initial page loads and history state changes (ideal for SPAs like React, Vue, Angular).
126
+ 2. **Scrolls (`scroll`)**:
127
+ - Fires when the user scrolls down to 90% of the page height.
128
+ 3. **Clicks (`click`)**:
129
+ - Captures interactions with links, buttons, and dropdowns.
130
+ - Automatically detects outbound links and logs the `link_url`, `button_type`, and the visible text (`element_text`) of the clicked element.
131
+ 4. **Site Search (`view_search_results`)**:
132
+ - Triggers when the URL contains specific query parameters (e.g., `?q=shoes`).
133
+ 5. **Form Interactions (`form_start`, `form_submit`)**:
134
+ - 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`.
135
+ 6. **File Downloads (`file_download`)**:
136
+ - Fires when a user clicks a link ending in common file extensions (like `.pdf`, `.zip`, `.docx`).
137
+
138
+ ---
139
+
140
+ ## Screen Activity Capture
141
+
142
+ The SDK supports capturing a visual snapshot of the user's screen during key interactions to provide deep insights into the user journey.
143
+
144
+ - By default, screen capture is securely controlled and can be dynamically enabled by the server (`debugScreenshotCapture`).
145
+ - Captures are throttled (default `2000ms`) to optimize performance.
146
+ - Only the visible `viewport` is captured by default to reduce payload size.
147
+
148
+ If enabled, screenshots are automatically attached to key events like `click`, `page_view`, and `form_submit`.