Pathing.js SDK

Pathing.js is a lightweight analytics tracking library that helps you understand user behavior in your application without compromising privacy.

Features

Predefined events (e.g. pathing.send.purchase({...}))
Dynamic element binding (e.g. pathing.link.purchase(element, {...}))
Raw fallback API (pathing.send.raw(...), pathing.link.raw(...))
Parameter wrapper support (Parameter(label, key, value))
Automatic pageview tracking

Installation

Option 1: Script Tag (Browser)

Add the following script tag before the closing </body> tag:

<script src="https://cdn.jsdelivr.net/npm/pathingjs/dist/pathing.min.js" pathing-api-key="YOUR_API_KEY"></script>

Option 2: NPM Package

Install the package:

npm install pathingjs

Then import in your application:

// ESM import (recommended)
import { pathing } from 'pathingjs';

// Or using default import
import pathing from 'pathingjs';

Usage

Tracking Events

Button Click

// Track a button click
pathing.send.button({
  buttonId: "signup-button",
  location: "homepage",
  action: "signup_click"
});

Playback Event

// Track a video or audio playback
pathing.send.playback({
  contentId: "video-123",
  timestamp: 42, // seconds into playback
  duration: 300, // total duration in seconds
  title: "How to Use Pathing.js"
});

Purchase Event

// Track a purchase
pathing.send.purchase({
  product: "premium-plan",
  price: 49.99,
  currency: "USD",
  quantity: 1
});

Custom Event

// Track any custom event
pathing.send.raw("form_submission", {
  formId: "contact-form",
  timeToComplete: 45, // seconds
  completed: true
});

Automatically Track DOM Elements

Link Buttons

// Automatically track when a button is clicked
const button = document.getElementById('signup-button');
pathing.link.button(button, {
  location: "homepage",
  action: "signup_click"
});

Link Playback

// Automatically track when a play button is clicked
const playButton = document.getElementById('play-button');
pathing.link.playback(playButton, {
  contentId: "video-123",
  timestamp: 0,
  title: "Getting Started"
});

Link Purchase

// Automatically track when a buy button is clicked
const buyButton = document.getElementById('buy-button');
pathing.link.purchase(buyButton, {
  product: "premium-plan",
  price: 49.99,
  currency: "USD"
});

React Example

import React, { useRef, useEffect } from 'react';
import { pathing } from 'pathingjs';

function SignupButton() {
  const buttonRef = useRef(null);
  
  useEffect(() => {
    if (buttonRef.current) {
      pathing.link.button(buttonRef.current, {
        location: "pricing-page",
        action: "signup_click",
        buttonId: "premium-signup"
      });
    }
  }, [buttonRef]);
  
  return (
    <button ref={buttonRef} className="signup-button">
      Sign Up Now
    </button>
  );
}

TypeScript Support

This library includes TypeScript definitions. You can import types directly:

import { pathing, ButtonData, EventResponse } from 'pathingjs';

function trackButtonClick(data: ButtonData): Promise<EventResponse> {
  return pathing.send.button(data);
}

API Reference

See full documentation for detailed API reference.

License

MIT