@bluenath/engage

The official analytics and attribution SDK for EngagePro. Production-ready event capture for campaign ROI measurement and creator attribution.

Developed by the Bluenath team.

Overview

@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.

Key Features

• Automated Event Capture: Seamlessly tracks high-value interactions including page views, commerce events, form submissions, and friction signals (e.g., rage-clicks).
• Manual Business Events: Flexible API for tracking custom conversions with support for value, currency, and campaign metadata.
• Resilient Delivery: Robust offline queueing mechanism with exponential backoff and retry logic.
• Framework Integration: Includes a lightweight React Provider and custom hooks for modern web architectures.
• Data Security: Built-in protection for sensitive input fields and secure handling of attribution identifiers.

Installation

Install the package via your preferred package manager:

npm install @bluenath/engage

Quick Start (React)

Initialize the SDK at the root of your application using the EngageProProvider.

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

ReactDOM.createRoot(document.getElementById("root")!).render(
  <EngageProProvider
    writeKey="YOUR_PUBLIC_WRITE_KEY"
    tracking={{
      autoTrack: true,
      useCookies: true,
      fingerprint: true,
    }}
  >
    <App />
  </EngageProProvider>,
);

Manual Event Tracking

Use the useAnalytics hook to capture specific business outcomes.

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

export function PurchaseConfirmation() {
  const analytics = useAnalytics();

  const handlePurchase = () => {
    analytics.track("PURCHASE", {
      orderId: "ORD-1029",
      amount: 4999,
      currency: "INR",
      ref: "camp_<campaignId>_cr_<creatorId>",
    });
  };

  return <button onClick={handlePurchase}>Confirm Payout</button>;
}

Attribution Reference Format

For accurate campaign attribution, ensure the ref field follows the standard EngagePro format: camp_<campaignId>_cr_<creatorId>

API Reference

Provider Configuration

| Property | Type | Required | Description | | :--- | :--- | :--- | :--- | | writeKey | string | Yes | Your public brand write key from the EngagePro Dashboard. | | apiHost | string | No | Local development override (restricted to localhost or 127.0.0.1). | | tracking.autoTrack | boolean | Yes | Enables automated DOM interaction capture. | | tracking.useCookies| boolean | Yes | Persists anonymous identifiers across sessions. | | tracking.fingerprint| boolean | Yes | Includes device context for fraud prevention and unique visit tracking. | | debug | boolean | No | Enables console logging for integration testing. |

Network & Security Policies

• Endpoint Isolation: Production data is exclusively routed to EngagePro's managed infrastructure.
• Local Development: The apiHost parameter is strictly limited to local environments for testing. External host overrides are rejected for security compliance.
• Security Best Practices:
  • Never expose internal service keys in client-side code.
  • Rotate write keys immediately if leakage is suspected.
  • Use hashed or anonymous identifiers; do not transmit raw PII (Personally Identifiable Information).

Resources

• Official Documentation
• EngagePro Platform
• Bluenath Creator OS

License

This project is licensed under the MIT License - see the LICENSE.md file for details.