@bluenath/engage

The intelligent, zero-configuration analytics SDK for modern React applications. @bluenath/engage automatically captures clicks, form submissions, and page views, using heuristic intelligence to classify user intent (Commerce, Frustration, Engagement) without manual tagging.

✨ Features

- 🧠 Auto-Capture Intelligence: Automatically detects ADD_TO_CART, CHECKOUT, REFUND, and more by analyzing button text and DOM attributes.
- 😡 Rage Click Detection: Detects user frustration (rapid clicking) automatically.
- ⚡️ Performance Monitoring: Tracks Core Web Vitals (LCP, TTFB, Load Time) out of the box.
- 🔌 Offline Support: Queues events in LocalStorage when offline and syncs when connectivity returns.
- 🛡️ PII Protection: Automatically ignores password and credit card fields.
- ⚛️ First-Class React Support: Drop-in Provider component.

🚀 Installation

``bash
npm install @bluenath/engage
`

or

`bash
yarn add @bluenath/engage
`

🛠️ Usage

$3

Wrap your root component with EngageProProvider. This single step enables auto-capture for the entire application.

`jsx
import React from "react";
import ReactDOM from "react-dom/client";
import { EngageProProvider } from "@bluenath/engage";
import App from "./App";

const root = ReactDOM.createRoot(document.getElementById("root"));

root.render(
writeKey="YOUR_WRITE_KEY"
apiHost="https://your-api.com/analyticsdk/ingest"
tracking={{
autoTrack: true, // 🧠 Enable Smart Sentinel
useCookies: true, // Persist session across subdomains
fingerprint: true, // Device fingerprinting for guest users
}}
>

,
);
`

$3

While auto-capture handles 90% of events, you can manually track specific actions using the hook.

`jsx
import { useAnalytics } from "@bluenath/engage";

const ProductPage = () => {
const { track, identify } = useAnalytics();

const handleLogin = (user) => {
// Stitch session to user ID
identify(user.id, {
email: user.email,
plan: "premium",
});
};

const handleCustomAction = () => {
track("Video Watched", {
duration: 120,
category: "Tutorial",
});
};

return Play Video;
};
`

🧠 Smart Events (Auto-Detected)

The SDK automatically maps user interactions to these standard events based on heuristics:

| Event Name | Trigger Logic (Example) |
| ------------------- | -------------------------------------------------- |
| ADD_TO_CART | Clicks on buttons labeled "Add to Cart", "Buy Now" |
| INITIATE_CHECKOUT | Clicks on "Checkout", "Proceed" |
| PURCHASE | Clicks on "Place Order", "Pay Now" |
| ORDER_CANCEL | Clicks on "Cancel Order" |
| RAGE_CLICK | 3+ rapid clicks on the same element (< 500ms) |
| FORM_START | User focuses on an input field |
| PERFORMANCE | Page Load metrics (TTFB, Load Time) |

🔒 Configuration Options

| Prop | Type | Default | Description |
| --------------------- | --------- | -------- | ----------------------------------------- |
| writeKey | string | Required | Your project's API Key. |
| apiHost | string | ... | The endpoint where events are sent. |
| tracking.autoTrack | boolean | true | Enables/Disables DOM listening. |
| tracking.useCookies | boolean | false | Use cookies for cross-subdomain tracking. |
| debug | boolean | false` | Log events to console for debugging. |

📄 License

MIT © Bluenath