@heuric/web-sdk

v1.0.0

Published

2 months ago

Easy setup SDK for tracking user interactions

Downloads

0High
0Medium
0Low

unknownturtle

analytics ux tracking web-sdk heuric

Heuric Web SDK

A lightweight, drop-in UX analytics SDK that automatically captures user interactions (clicks and scrolls) and sends them to your backend in clean, privacy-focused batches.

Installation

Install the package via npm:

npm install @heuric/web-sdk

Alternative Local Installation

Download the repository.
Run npm install and then npm run build.
Copy the resulting dist/heuric.esm.js file into your own project (e.g., src/lib/heuric.esm.js).

Usage and Setup

1. Initialise the SDK

Initialise the SDK once in your application's root component or layout.

For Next.js / React (App Router): Create a client component (Tracker.tsx):

"use client";

import { useEffect } from "react";
import { initHeuric } from "@heuric/web-sdk"; // or "@/lib/heuric.esm.js" if using local installation

export default function HeuricTracker() {
  useEffect(() => {
    initHeuric({
      endpoint: "https://your-api.com/webhooks/events",
      projectId: "your-project-id",
      // Optional: flushInterval: 5000, 
      // Optional: flushThreshold: 20
    });
  }, []);

  return null;
}

2. Add to your Root Layout

Add the <HeuricTracker /> component into your main layout so it runs on every page:

import HeuricTracker from "./components/HeuricTracker";

export default function RootLayout({ children }) {
  return (
    <html lang="en">
      <body>
        <HeuricTracker />
        {children}
      </body>
    </html>
  );
}

3. Setup Supabase Database Table

To actually catch and store the data your SDK captures, you need a database table mapped to the specific JSON payload.

Create a project on Supabase.
Open the SQL Editor in your Supabase dashboard.
Run the SQL schema in supabase/schema.sql to create your events table. (We use JSONB columns so you can change the payload later without breaking your database).

4. Deploy the Ingestion API

The SDK cannot communicate directly to your database securely. So I have provided a pre-configured Supabase Edge Function that handles CORS and safely inserts the data.

Install the Supabase CLI and log in.

Open your terminal in the project's root folder and link this folder to your Supabase project:

# You can find the project-ref in your Supabase dashboard URL
supabase link --project-ref <your-project-ref>

Deploy the ingestion function (note: this bypasses JWT checks so the public SDK can freely send data):
```
supabase functions deploy collect
```
Retrieve the endpoint URL from the dashboard and use it to update your endpoint from Step 1. The link will be given to you in the terminal (e.g. https://supabase.com/dashboard/project//functions).

5. View Your Live Data

That's it! Your UX tracker is now fully operational. As users interact with your application, you will immediately see live UX analytics data populate the events table inside your Supabase dashboard.

Privacy, Security and Performance Defaults

By default, the SDK heavily prioritises user privacy:

Password and hidden inputs are strictly ignored.
Credit Card inputs (autocomplete="cc-*") are ignored.
Emails and Numbers inside clicked text are scrubbed and replaced with [EMAIL] and [NUMBER] before being sent to your database.
Elements with the .heuric-ignore class are completely ignored by the click tracker.
The SDK uses navigator.sendBeacon with text/plain blobs to bypass aggressive CORS preflights, ensuring your event batches arrive safely even on cross-origin requests.

Testing Locally

If you want to quickly test how the SDK behaves without installing it in a full React application, we provide a standalone test playground.

Start a local server in the project root (try python3 -m http.server 3456 because browsers usually block modules from loading with file:// protocol).
Open http://localhost:3456/test.html in your browser.
At the bottom of the file, replace the endpoint with a testing webhook (like Webhook.site) (or just right-click > Inspect Element > Network).
Click around the page, scroll down, and watch your webhook site or browser's Network tab for POST requests.