@taskip/analytics

Client-side analytics SDK for Taskip — cross-domain attribution, event tracking, and marketing channel intelligence.

Installation

npm install @taskip/analytics

Setup

import { TaskipAnalytics } from '@taskip/analytics';

const analytics = new TaskipAnalytics({
  endpoint: 'https://analytics.taskip.net',
  writeKey: 'wi_...',
  debug: true,
});

Getting your credentials

Create an API app in the Developer Settings → API Keys page of the Taskip Analytics dashboard. Each app gets a unique write key. Use that write key here.

Options

| Option | Default | Description | |--------|---------|-------------| | endpoint | — | Analytics API URL | | writeKey | — | Write key from Developer Settings → API Keys | | enabled | true | Enable/disable all tracking | | flushThreshold | 10 | Flush after this many queued events | | flushInterval | 30000 | Flush interval in ms | | cookieDomain | '.taskip.net' | Domain for cross-subdomain attribution cookies | | debug | false | Log events to console | | affonso.accountId | — | Affonso affiliate tracking account ID |

Core API

track(event, properties?)

Send a custom event.

analytics.track('invoice_sent', {
  invoiceId: 'inv_123',
  amount: 1200,
});

page(options)

Track a page view. Auto-attaches referrer and title.

analytics.page({ name: 'Pricing', path: '/pricing' });

identify(traits)

Attach user/workspace identity. Persisted in cookies + localStorage.

analytics.identify({
  userId: 'usr_abc',
  email: '[email protected]',
  workspace: 'tn-perchco',
  plan: 'Pro',
});

signupSource is auto-populated from the last page visited before identify() was called.

getAttribution()

Get current attribution data (UTMs, referrer, AI source, etc.).

const attr = analytics.getAttribution();

captureAttribution()

Re-capture attribution from current URL. Call after client-side navigation.

analytics.captureAttribution();

getIdentity()

Get current identity data.

flush()

Force-send all queued events immediately.

destroy()

Flush remaining events and clear the flush timer.

Free Tools & Templates

Convenience methods for tracking free tool and template interactions.

analytics.freeToolViewed('Invoice Generator');
analytics.freeToolUsed('Invoice Generator', 'download');

analytics.templateViewed('Invoice Template');
analytics.templateUsed('Invoice Template', 'copy');

These fire free_tool_viewed, free_tool_used, template_viewed, template_used events.

Attribution

SDK captures these on initialization and every captureAttribution() call:

| Signal | Source | Example | |--------|--------|---------| | UTM params | URL query | ?utm_source=google&utm_medium=cpc | | Google Ads | URL + cookie | gclid, wbraid, gbraid | | Meta/Facebook | Cookie | fbp, fbc | | TikTok | URL + session | ttclid | | Content referral | URL query | ?rel=blog, ?rel=docs | | Affiliate | URL query | ?via=ref123, ?aff=ref123 | | Referrer | document.referrer | https://google.com | | AI source | Referrer domain | ChatGPT, Claude, Perplexity, Gemini, Copilot, DeepSeek, Mistral, Grok | | Landing page | First page in session | Preserved in cookie | | Last seen page | Updated on every capture | Used as signupSource on identify |

React

usePageView(analytics)

Auto-tracks page views on route changes. Works with Next.js App Router and any React Router.

import { useMemo } from 'react';
import { TaskipAnalytics, usePageView } from '@taskip/analytics/react';

function App() {
  const analytics = useMemo(() => new TaskipAnalytics({
    endpoint: 'https://analytics.taskip.net',
    writeKey: 'wk_...',
  }), []);

  usePageView(analytics);

  return <Routes>...</Routes>;
}

Affiliate Tracking (Affonso)

const analytics = new TaskipAnalytics({
  endpoint: 'https://analytics.taskip.net',
  writeKey: 'wk_...',
  affonso: {
    accountId: 'acc_123',
  },
});

// On signup/conversion:
analytics.affonsoSignup('[email protected]');

// On checkout — attach to Stripe:
analytics.getAffiliateMetadata();
// → { affonso_referral: 'ref123', affiliate_id: 'ref123', ... }

Performance

• Events queue in memory and flush every 30s (or when 10 events accumulate)
• Uses navigator.sendBeacon for reliable delivery on page unload
• No blocking calls on the main thread
• Failed events are re-queued for the next flush cycle

TypeScript

import type {
  AnalyticsConfig,
  AnalyticsEvent,
  EventContext,
  AttributionData,
  UserIdentity,
  PageViewOptions,
} from '@taskip/analytics';