flux-analytics-sdk 1.0.0 → 1.0.1
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.
- package/README.md +95 -0
- package/package.json +2 -2
- package/src/Flux.js +4 -1
package/README.md
ADDED
|
@@ -0,0 +1,95 @@
|
|
|
1
|
+
# Flux Analytics SDK (JS/Web)
|
|
2
|
+
|
|
3
|
+
This is the official JavaScript/Web SDK for Flux Analytics. It is designed to work seamlessly with the Flux Dashboard and Supabase backend, providing feature parity with the Flutter SDK.
|
|
4
|
+
|
|
5
|
+
## Installation
|
|
6
|
+
|
|
7
|
+
```bash
|
|
8
|
+
npm install flux-analytics-sdk
|
|
9
|
+
```
|
|
10
|
+
|
|
11
|
+
## Quick Start
|
|
12
|
+
|
|
13
|
+
### 1. Initialize
|
|
14
|
+
Initialize the SDK at the root of your application (e.g., `index.js`, `App.js`, or `main.ts`).
|
|
15
|
+
|
|
16
|
+
```javascript
|
|
17
|
+
import Flux from 'flux-analytics-sdk';
|
|
18
|
+
|
|
19
|
+
Flux.init(
|
|
20
|
+
'YOUR_APP_ID', // UUID (Application ID from Dashboard)
|
|
21
|
+
'YOUR_FIRM_ID', // UUID (Firm/Workspace ID)
|
|
22
|
+
{
|
|
23
|
+
// Optional: Only needed if you are self-hosting or using a proxy
|
|
24
|
+
// baseUrl: 'https://your-proxy.com',
|
|
25
|
+
debug: true // Set to true to see logs in console
|
|
26
|
+
}
|
|
27
|
+
);
|
|
28
|
+
```
|
|
29
|
+
|
|
30
|
+
> **Note:** The SDK comes pre-configured with the default Flux Cloud credentials. You do not need to provide an API Key unless you are using a custom instance.
|
|
31
|
+
|
|
32
|
+
### 2. Track Events
|
|
33
|
+
Track any custom event with optional metadata.
|
|
34
|
+
|
|
35
|
+
```javascript
|
|
36
|
+
// Simple event
|
|
37
|
+
Flux.track('button_clicked');
|
|
38
|
+
|
|
39
|
+
// Event with metadata
|
|
40
|
+
Flux.track('purchase_completed', {
|
|
41
|
+
item_id: 'sku_123',
|
|
42
|
+
price: 99.99,
|
|
43
|
+
currency: 'USD'
|
|
44
|
+
});
|
|
45
|
+
```
|
|
46
|
+
|
|
47
|
+
### 3. Identity Management
|
|
48
|
+
Link sessions to a specific user ID once they log in.
|
|
49
|
+
|
|
50
|
+
```javascript
|
|
51
|
+
// When user logs in
|
|
52
|
+
Flux.identify('user_123456');
|
|
53
|
+
```
|
|
54
|
+
|
|
55
|
+
## Features & Technical Details
|
|
56
|
+
|
|
57
|
+
### 1. Automatic Session Management
|
|
58
|
+
- **Session Start**: Automatically tracks `session_start` when `Flux.init()` is called.
|
|
59
|
+
- **Session ID**: Generated (UUID v4) and persisted in memory for the duration of the page lifecycle.
|
|
60
|
+
- **Anonymous ID**: A persistent UUID is generated and stored in `localStorage` (`flux_anonymous_id`) to track unauthenticated users across sessions.
|
|
61
|
+
|
|
62
|
+
### 2. Offline Support (Queue System)
|
|
63
|
+
- Events are not sent immediately if the device is offline.
|
|
64
|
+
- **Storage**: Events are stored in `localStorage` under the key `flux_event_queue`.
|
|
65
|
+
- **Sync**: The SDK automatically listens for the `online` window event and flushes the queue when the connection is restored.
|
|
66
|
+
- **Retry Logic**: Failed requests (non-4xx/5xx) are kept in the queue for retry.
|
|
67
|
+
|
|
68
|
+
### 3. Automatic Metadata
|
|
69
|
+
Every event automatically includes the following metadata:
|
|
70
|
+
- `platform`: 'web'
|
|
71
|
+
- `os_version`: Browser/OS details
|
|
72
|
+
- `user_agent`: Raw User-Agent string
|
|
73
|
+
- `language`: Browser language (e.g., 'en-US')
|
|
74
|
+
- `resolution`: Screen resolution (e.g., '1920x1080')
|
|
75
|
+
- `timezone`: User's timezone
|
|
76
|
+
- `page_url`: Current URL
|
|
77
|
+
- `referrer`: Previous URL (document.referrer)
|
|
78
|
+
|
|
79
|
+
### 4. Attribution (Marketing Tracking)
|
|
80
|
+
The SDK automatically checks URL parameters for marketing campaigns.
|
|
81
|
+
- **Parameters**: Looks for `campaign_id` (or `utm_campaign`) and `click_id` (or `gclid`).
|
|
82
|
+
- **Persistence**: If found, these are stored and attached to the `app_install` (first visit) event and subsequent events.
|
|
83
|
+
|
|
84
|
+
### 5. API Compatibility
|
|
85
|
+
The SDK communicates directly with the Flux/Supabase backend using the following endpoints:
|
|
86
|
+
- **Events**: `POST /rpc/insert_event_v2` (High-performance ingestion)
|
|
87
|
+
- **Sessions**: `POST /sessions` (Upsert on `session_id`)
|
|
88
|
+
- **Installs**: `POST /installs` (Tracked only once per device via `localStorage` flag `flux_app_installed`)
|
|
89
|
+
|
|
90
|
+
## AI / LLM Context
|
|
91
|
+
If you are an AI Assistant integrating this SDK:
|
|
92
|
+
1. Ensure `Flux.init` is called as early as possible.
|
|
93
|
+
2. Use `Flux.trackScreen(screenName)` on route changes for SPA (Single Page Applications).
|
|
94
|
+
3. The `app_id` and `firm_id` MUST be valid UUIDs.
|
|
95
|
+
4. The SDK handles authentication automatically. You do NOT need to ask the user for an API Key.
|
package/package.json
CHANGED
package/src/Flux.js
CHANGED
|
@@ -14,7 +14,10 @@ const Flux = (function () {
|
|
|
14
14
|
|
|
15
15
|
// Base URL for API
|
|
16
16
|
let _baseUrl = 'https://cnpawrfdekifurtkdblw.supabase.co/rest/v1';
|
|
17
|
-
|
|
17
|
+
|
|
18
|
+
// PUBLIC ANON KEY (Safe to expose in client-side code, restricted by RLS)
|
|
19
|
+
const _defaultApiKey = 'eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJpc3MiOiJzdXBhYmFzZSIsInJlZiI6ImNucGF3cmZkZWtpZnVydGtkYmx3Iiwicm9sZSI6ImFub24iLCJpYXQiOjE3Njk2NzgyOTQsImV4cCI6MjA4NTI1NDI5NH0.IiMIagP7Guy1SsiWF4OdDmz1X6EwPkT4tWCumQLZXhg';
|
|
20
|
+
let _apiKey = _defaultApiKey;
|
|
18
21
|
|
|
19
22
|
// Constants
|
|
20
23
|
const _queueKey = 'flux_event_queue';
|