@bluenath/engage

The official event tracking SDK for EngagePro. EngagePro provides high-performance, robust product analytics and conversion tracking for modern e-commerce applications.

Installation

Install the package using your preferred package manager:

npm install @bluenath/engage

Quick Start

React and Next.js Applications

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

import React from "react";
import { EngageProProvider } from "@bluenath/engage";
import App from "./App";

export default function Root({ children }) {
  return (
    <EngageProProvider
      apiKey="YOUR_PUBLIC_API_KEY"
      tracking={{
        autoTrack: true,
        useCookies: true,
        fingerprint: true,
      }}
    >
      {children}
    </EngageProProvider>
  );
}

To track events or identify users in a component, use the useAnalytics hook:

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

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

  const handlePurchase = () => {
    analytics.track("PURCHASE", {
      amount: 4999,
      currency: "USD",
      ref: "campaign_123",
    });
  };

  return <button onClick={handlePurchase}>Complete Purchase</button>;
}

Vanilla JavaScript Applications

Import and initialize the core engage instance at the entry point of your application:

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

// Initialize once
engage.init({
  apiKey: "YOUR_PUBLIC_API_KEY",
  tracking: {
    autoTrack: true,
    useCookies: true,
    fingerprint: true
  }
});

// Manual event tracking
engage.track("PURCHASE", {
  amount: 2999,
  currency: "USD"
});

Best Practices for Zero-Code Integration

When autoTrack is enabled, EngagePro automatically monitors the DOM for user interactions. To ensure absolute data accuracy without writing manual tracking code, attach our custom HTML attributes to your interactive elements.

Our SDK is heavily optimized and operates securely in the background without degrading your application's performance.

Recommended Attributes

Add these attributes to your buttons, links, or product containers:

• data-engage-product-id: The unique identifier (SKU or ID) of the product.
• data-engage-product-name: The name of the product.
• data-engage-price: The numerical price of the product (e.g., "19.99").
• data-engage-currency: The currency code (e.g., "USD", "EUR").
• data-engage-category: The product category or collection.
• data-engage-action: A custom label for the interaction (e.g., "Hero Banner Click").

Example Component

export function ProductCard({ product }) {
  return (
    <div 
      className="product-card"
      data-engage-product-id={product.id}
      data-engage-product-name={product.name}
      data-engage-category={product.category}
    >
      <h3>{product.name}</h3>
      <p>${product.price}</p>
      
      <button 
        data-engage-action="Quick Add"
        data-engage-price={product.price}
        data-engage-currency="USD"
      >
        Add to Cart
      </button>
    </div>
  );
}

Campaign & Creator Attribution

EngagePro SDK includes built-in support for cryptographically signed campaign and creator attribution:

• Automated Ref Extraction: The SDK automatically parses the ep_ref query parameter from the landing page URL and stores it.
• Session Persistence: The ref is persisted across pageviews during the session, so you do not need to manually pass the reference parameter to subsequent track calls.
• Downstream Linking: When users trigger a conversion event (such as PURCHASE or SIGNUP), the SDK automatically attaches the verified campaign context, facilitating attribution, click deduplication, and fraud verification on the server side.

Configuration Options

| Property | Type | Required | Description | | :--- | :--- | :--- | :--- | | apiKey | string | Yes | Your public brand API key from the EngagePro Dashboard. | | tracking.autoTrack | boolean | Yes | Enables automated interaction capture. | | tracking.useCookies| boolean | Yes | Persists 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. |

Documentation and Resources

For detailed API references and integration guides, please visit our website and documentation:

• EngagePro Website
• EngagePro Documentation