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
• Enhanced device and browser fingerprinting
• Session and user tracking across visits
• Performance and network data collection
• Scroll depth and engagement metrics

Installation

Option 1: Script Tag (Browser)

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

<script src="https://www.pathing.cc/pathing.js" pathing-api-key="YOUR_API_KEY"></script>

Option 2: NPM Package

Install the package:

npm install pathingjs

Then import and initialize in your application:

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

// Initialize with your API key
pathing.init('pk_[YOUR_API_KEY]');

// Or using default import
import pathing from 'pathingjs';
pathing.init('pk_[YOUR_API_KEY]');

Usage

When loaded via script tag, the pathing object is now available globally as window.pathing (or just pathing in browser context).

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"
});

Tracked Data

The latest version of Pathing.js automatically collects a comprehensive set of data with each event:

Device Information

• Browser details (user agent, language, screen dimensions)
• Device type and capabilities
• Platform and operating system information
• Connection speed and network type
• Browser fingerprint for cross-session tracking

Session Information

• Session ID and duration
• First and last seen timestamps
• Page entry points and navigation paths
• Referrer information
• Visit count and frequency

Engagement Metrics

• Time on page and scroll depth
• Tab visibility and focus tracking
• Page exit events with engagement data
• Element interactions (clicks, hovers)

Performance Data

• Page load time and render metrics
• Navigation timing data
• Memory usage statistics
• Resource loading performance

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';

// Initialize with your API key
pathing.init('pk_[YOUR_API_KEY]');

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

API Reference

See full documentation for detailed API reference.

License

MIT