datafast

Official DataFast SDK for web apps. Use this if you prefer npm packages over the script tag.

Installation

npm install datafast

Quick Start

Same API as in the DataFast docs: use initDataFast once, then call trackPageview(), track(), identify(), and trackPayment(). All methods are async and return Promises.

import { initDataFast } from 'datafast';

const datafast = await initDataFast({
  websiteId: 'your-website-id',
  domain: 'yourdomain.com', // optional, defaults to current hostname
  autoCapturePageviews: true, // optional: capture initial + SPA route changes
});

// Track page views
datafast.trackPageview();
// Or pass a path (e.g. for SPAs)
datafast.trackPageview('/pricing');

// Track custom events
datafast.track('button_click', { button: 'signup' });

// Identify users
datafast.identify('user_123', { email: '[email protected]', plan: 'pro' });

// Track payments (email-based)
datafast.trackPayment({ email: '[email protected]', amount: 99, currency: 'USD' });

// Or provider-ID based payment tracking
datafast.trackPayment({ stripe_session_id: 'cs_test_123' });

// Reset visitor identity (e.g. on logout)
datafast.reset();

With React / Next.js

// lib/analytics.ts
import { initDataFast } from 'datafast';

let datafast: Awaited<ReturnType<typeof initDataFast>> | null = null;

export async function getAnalytics() {
  if (!datafast) {
    datafast = await initDataFast({
      websiteId: process.env.NEXT_PUBLIC_DATAFAST_WEBSITE_ID!,
      domain: process.env.NEXT_PUBLIC_DATAFAST_DOMAIN,
    });
  }
  return datafast;
}

Then in your app:

import { getAnalytics } from '@/lib/analytics';

export default function SignupButton() {
  const handleSignup = async () => {
    const analytics = await getAnalytics();
    analytics.track('signup', { plan: 'free', source: 'homepage' });
  };

  return <button onClick={handleSignup}>Sign Up</button>;
}

API

initDataFast(config) → Promise<DataFastWeb>

Initialize the SDK. Returns a client with trackPageview, track, identify, trackPayment, reset, and flush.

Config (DataFastWebConfig)

{
  websiteId: string;        // Required: Your DataFast website ID
  domain?: string;          // Optional: Defaults to current hostname
  apiUrl?: string;          // Optional: Custom API endpoint
  debug?: boolean;          // Optional: Enable debug logging
  flushInterval?: number;   // Optional: ms between flushes (default: 5000)
  maxQueueSize?: number;    // Optional: max events before flush (default: 10)
  autoCapturePageviews?: boolean | {
    enabled?: boolean;          // Default true when object is provided
    trackHashChanges?: boolean; // Default false
    captureInitialPageview?: boolean; // Default true
    debounceMs?: number;        // Default 100
  };
  allowLocalhost?: boolean;   // Allow tracking on localhost (default: false)
  allowIframe?: boolean;      // Allow tracking inside iframes (default: false)
  allowedHostnames?: string[]; // Hostnames for cross-domain tracking
}

When autoCapturePageviews is enabled, the SDK will:

• capture one initial pageview after initDataFast
• capture subsequent pageviews on history.pushState, history.replaceState, and back/forward (popstate)
• optionally include hash-route changes when trackHashChanges: true

By default, tracking is silently disabled on localhost, file:// protocol, inside iframes, and for bots/headless browsers. Set allowLocalhost: true for local development.

datafast.trackPageview(path?) → Promise<void>

Track a page view. Omit path to use window.location.href (full URL including query params, UTMs, and ad click IDs). Pass a path for manual override. Duplicate pageviews for the same URL within 60 seconds are automatically skipped.

datafast.track(eventName, properties?) → Promise<void>

Track a custom event. properties is optional and must be Record<string, string | number | boolean>.

await datafast.track('purchase', { product: 'Pro Plan', price: 99 });

datafast.identify(userId, properties?) → Promise<void>

Identify a logged-in user.

await datafast.identify('user_123', { name: 'John', email: '[email protected]' });

datafast.trackPayment(data) → Promise<void>

Track a payment. data must include one of: email, stripe_session_id, lemonsqueezy_order_id, polar_checkout_id, paddle_transaction_id. amount and currency are optional.

await datafast.trackPayment({ email: '[email protected]', amount: 99, currency: 'USD' });
await datafast.trackPayment({ stripe_session_id: 'cs_test_123' });

datafast.reset() → Promise<void>

Reset visitor identity (e.g. on logout). New visitor and session IDs are generated.

datafast.flush() → Promise<void>

Flush all queued events immediately.

datafast.getTrackingParams() → { _df_vid: string; _df_sid: string }

Get the current visitor and session IDs for cross-domain tracking.

datafast.buildCrossDomainUrl(url) → string

Append visitor/session tracking params to a URL for cross-domain navigation.

const url = datafast.buildCrossDomainUrl('https://other-domain.com/signup');
// => 'https://other-domain.com/signup?_df_vid=abc-123&_df_sid=s456-789'

On the receiving domain, initDataFast automatically picks up the params and restores the visitor/session.

Script Tag Alternative

If you prefer not to use npm, add the script tag instead:

<script src="https://datafa.st/script.js" data-website-id="your-website-id" async defer></script>

License

MIT