@bluenath/engage 2.0.2 → 2.0.3
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 +51 -39
- package/package.json +1 -1
package/README.md
CHANGED
|
@@ -1,25 +1,35 @@
|
|
|
1
1
|
# @bluenath/engage
|
|
2
2
|
|
|
3
|
-
|
|
3
|
+
The official analytics and attribution SDK for [EngagePro](https://engagepro.bluenath.com). Production-ready event capture for campaign ROI measurement and creator attribution.
|
|
4
4
|
|
|
5
|
-
|
|
5
|
+
Developed by the [Bluenath](https://bluenath.com) team.
|
|
6
6
|
|
|
7
|
-
|
|
7
|
+
---
|
|
8
8
|
|
|
9
|
-
|
|
10
|
-
|
|
11
|
-
-
|
|
12
|
-
|
|
13
|
-
|
|
9
|
+
## Overview
|
|
10
|
+
|
|
11
|
+
`@bluenath/engage` is a high-performance analytics SDK designed to bridge the gap between user interactions and campaign attribution. It captures critical web events, enriches intent signals, and securely transmits batched payloads to EngagePro's ingestion servers for real-time ROI analysis.
|
|
12
|
+
|
|
13
|
+
## Key Features
|
|
14
|
+
|
|
15
|
+
- **Automated Event Capture**: Seamlessly tracks high-value interactions including page views, commerce events, form submissions, and friction signals (e.g., rage-clicks).
|
|
16
|
+
- **Manual Business Events**: Flexible API for tracking custom conversions with support for value, currency, and campaign metadata.
|
|
17
|
+
- **Resilient Delivery**: Robust offline queueing mechanism with exponential backoff and retry logic.
|
|
18
|
+
- **Framework Integration**: Includes a lightweight React Provider and custom hooks for modern web architectures.
|
|
19
|
+
- **Data Security**: Built-in protection for sensitive input fields and secure handling of attribution identifiers.
|
|
14
20
|
|
|
15
21
|
## Installation
|
|
16
22
|
|
|
23
|
+
Install the package via your preferred package manager:
|
|
24
|
+
|
|
17
25
|
```bash
|
|
18
26
|
npm install @bluenath/engage
|
|
19
27
|
```
|
|
20
28
|
|
|
21
29
|
## Quick Start (React)
|
|
22
30
|
|
|
31
|
+
Initialize the SDK at the root of your application using the `EngageProProvider`.
|
|
32
|
+
|
|
23
33
|
```tsx
|
|
24
34
|
import React from "react";
|
|
25
35
|
import ReactDOM from "react-dom/client";
|
|
@@ -40,60 +50,62 @@ ReactDOM.createRoot(document.getElementById("root")!).render(
|
|
|
40
50
|
);
|
|
41
51
|
```
|
|
42
52
|
|
|
43
|
-
## Manual Tracking
|
|
53
|
+
## Manual Event Tracking
|
|
54
|
+
|
|
55
|
+
Use the `useAnalytics` hook to capture specific business outcomes.
|
|
44
56
|
|
|
45
57
|
```tsx
|
|
46
58
|
import { useAnalytics } from "@bluenath/engage";
|
|
47
59
|
|
|
48
|
-
export function
|
|
60
|
+
export function PurchaseConfirmation() {
|
|
49
61
|
const analytics = useAnalytics();
|
|
50
62
|
|
|
51
|
-
const
|
|
63
|
+
const handlePurchase = () => {
|
|
52
64
|
analytics.track("PURCHASE", {
|
|
53
|
-
orderId: "ORD-
|
|
54
|
-
amount:
|
|
65
|
+
orderId: "ORD-1029",
|
|
66
|
+
amount: 4999,
|
|
55
67
|
currency: "INR",
|
|
56
68
|
ref: "camp_<campaignId>_cr_<creatorId>",
|
|
57
69
|
});
|
|
58
70
|
};
|
|
59
71
|
|
|
60
|
-
return <button onClick={
|
|
72
|
+
return <button onClick={handlePurchase}>Confirm Payout</button>;
|
|
61
73
|
}
|
|
62
74
|
```
|
|
63
75
|
|
|
64
|
-
|
|
76
|
+
### Attribution Reference Format
|
|
65
77
|
|
|
66
|
-
For campaign
|
|
67
|
-
|
|
68
|
-
```text
|
|
69
|
-
camp_<campaignId>_cr_<creatorId>
|
|
70
|
-
```
|
|
78
|
+
For accurate campaign attribution, ensure the `ref` field follows the standard EngagePro format:
|
|
79
|
+
`camp_<campaignId>_cr_<creatorId>`
|
|
71
80
|
|
|
72
|
-
|
|
81
|
+
## API Reference
|
|
73
82
|
|
|
74
|
-
|
|
83
|
+
### Provider Configuration
|
|
75
84
|
|
|
76
|
-
|
|
77
|
-
|
|
78
|
-
|
|
85
|
+
| Property | Type | Required | Description |
|
|
86
|
+
| :--- | :--- | :--- | :--- |
|
|
87
|
+
| `writeKey` | `string` | **Yes** | Your public brand write key from the [EngagePro Dashboard](https://engagepro.bluenath.com/app/integration). |
|
|
88
|
+
| `apiHost` | `string` | No | Local development override (restricted to `localhost` or `127.0.0.1`). |
|
|
89
|
+
| `tracking.autoTrack` | `boolean` | **Yes** | Enables automated DOM interaction capture. |
|
|
90
|
+
| `tracking.useCookies`| `boolean` | **Yes** | Persists anonymous identifiers across sessions. |
|
|
91
|
+
| `tracking.fingerprint`| `boolean` | **Yes** | Includes device context for fraud prevention and unique visit tracking. |
|
|
92
|
+
| `debug` | `boolean` | No | Enables console logging for integration testing. |
|
|
79
93
|
|
|
80
|
-
##
|
|
94
|
+
## Network & Security Policies
|
|
81
95
|
|
|
82
|
-
|
|
83
|
-
|
|
84
|
-
|
|
85
|
-
|
|
86
|
-
|
|
87
|
-
|
|
88
|
-
| `tracking.fingerprint` | `boolean` | Yes | Include device fingerprint context |
|
|
89
|
-
| `debug` | `boolean` | No | Log payloads in console for integration testing |
|
|
96
|
+
- **Endpoint Isolation**: Production data is exclusively routed to EngagePro's managed infrastructure.
|
|
97
|
+
- **Local Development**: The `apiHost` parameter is strictly limited to local environments for testing. External host overrides are rejected for security compliance.
|
|
98
|
+
- **Security Best Practices**:
|
|
99
|
+
- Never expose internal service keys in client-side code.
|
|
100
|
+
- Rotate write keys immediately if leakage is suspected.
|
|
101
|
+
- Use hashed or anonymous identifiers; do not transmit raw PII (Personally Identifiable Information).
|
|
90
102
|
|
|
91
|
-
##
|
|
103
|
+
## Resources
|
|
92
104
|
|
|
93
|
-
-
|
|
94
|
-
-
|
|
95
|
-
-
|
|
105
|
+
- [Official Documentation](https://engagepro.bluenath.com/docs)
|
|
106
|
+
- [EngagePro Platform](https://engagepro.bluenath.com)
|
|
107
|
+
- [Bluenath Creator OS](https://bluenath.com)
|
|
96
108
|
|
|
97
109
|
## License
|
|
98
110
|
|
|
99
|
-
MIT
|
|
111
|
+
This project is licensed under the MIT License - see the [LICENSE.md](LICENSE.md) file for details.
|