@clocsy/track

v1.0.0

Published

2 months ago

Clocsy Brand Intelligence SDK — domain verification, pageview intelligence, CPA conversion tracking, and affiliate identity linking.

0High
0Medium
0Low

spurprotocol

clocsy analytics tracking cpa conversion seo marketing growth-engine brand-intelligence

@clocsy/track

Clocsy Brand Intelligence SDK — domain verification, pageview intelligence, CPA conversion tracking, and affiliate identity linking.

Why

If you're using Clocsy to grow your business, the SDK connects your live website to the Clocsy intelligence engine. It handles:

Domain verification — auto-fires when your site loads, granting the "Website Verified" badge in your dashboard
Pageview intelligence — tracks navigation, referrers, UTM parameters, and screen dimensions
CPA conversion tracking — fires conversion events that trigger affiliate payouts and campaign attribution
Affiliate identity linking — de-duplicates users across devices for accurate referral tracking
SPA support — auto-detects pushState/popstate route changes in React, Next.js, Vue, etc.

Install

npm install @clocsy/track

yarn add @clocsy/track

pnpm add @clocsy/track

Quick Start

import { init, track, identify } from '@clocsy/track';

// 1. Initialize once at app startup
init({
  projectId: 'proj_abc123',   // from Clocsy Brand Settings
  token: 'tok_xyz',           // from Clocsy Brand Settings
});

// 2. Track a conversion event
track('signup_complete', { value: 49.00, currency: 'USD' });

// 3. Identify a user for affiliate attribution
identify('[email protected]', { plan: 'pro' });

Framework Examples

React (Vite / CRA)

// src/main.tsx
import { init } from '@clocsy/track';

init({
  projectId: 'proj_abc123',
  token: 'tok_xyz',
});

Next.js App Router

// app/providers.tsx
'use client';

import { useEffect } from 'react';
import { init } from '@clocsy/track';

export function ClocsyProvider({ children }: { children: React.ReactNode }) {
  useEffect(() => {
    init({
      projectId: 'proj_abc123',
      token: 'tok_xyz',
    });
  }, []);

  return <>{children}</>;
}

// app/layout.tsx
import { ClocsyProvider } from './providers';

export default function RootLayout({ children }: { children: React.ReactNode }) {
  return (
    <html lang="en">
      <body>
        <ClocsyProvider>{children}</ClocsyProvider>
      </body>
    </html>
  );
}

Next.js Pages Router

// pages/_app.tsx
import { useEffect } from 'react';
import { init } from '@clocsy/track';

export default function App({ Component, pageProps }) {
  useEffect(() => {
    init({ projectId: 'proj_abc123', token: 'tok_xyz' });
  }, []);

  return <Component {...pageProps} />;
}

Vue 3

// main.ts
import { createApp } from 'vue';
import { init } from '@clocsy/track';
import App from './App.vue';

init({ projectId: 'proj_abc123', token: 'tok_xyz' });

createApp(App).mount('#app');

Nuxt 3

// plugins/clocsy.client.ts
import { init } from '@clocsy/track';

export default defineNuxtPlugin(() => {
  init({ projectId: 'proj_abc123', token: 'tok_xyz' });
});

API Reference

`init(config: ClocsyConfig): void`

Initialize the SDK. Call once at app startup. Automatically fires a verification ping and an initial pageview.

| Option | Type | Default | Description | |--------|------|---------|-------------| | projectId | string | required | Your Clocsy project ID | | token | string | required | Domain verification token | | apiBase | string | https://api.clocsy.com | Override API base URL | | disableAutoPageview | boolean | false | Skip auto pageview on init | | debug | boolean | false | Log beacons to console |

`track(event: string, meta?: TrackMeta): void`

Track a conversion event. If a CPA campaign exists for this event, Clocsy automatically credits the referring affiliate.

track('purchase', { value: 99.00, currency: 'USD' });
track('trial_start');
track('app_install', { platform: 'ios' });

`identify(identity: string, meta?: IdentifyMeta): void`

Link the current session to a user identity for cross-device de-duplication.

identify('[email protected]', { plan: 'enterprise' });

`pageview(): void`

Manually fire a pageview beacon. Auto-fires on init and on SPA route changes by default.

// Custom route change handling
router.afterEach(() => {
  pageview();
});

SSR Safety

All SDK methods are server-side rendering (SSR) safe. When imported in a server environment (Next.js Server Components, Nuxt SSR, Node.js), all methods become silent no-ops — no errors, no warnings, no crashes.

// This is safe in a Server Component — it simply does nothing
import { init } from '@clocsy/track';
init({ projectId: 'proj_abc123', token: 'tok_xyz' });
// ↑ No-op on server, active on client

How It Works

Verification Ping: On init(), the SDK sends a POST to /sdk/verify with your project ID and token. This grants the "Website Verified" badge in your Clocsy dashboard.
Pageview Tracking: The SDK captures the current URL, path, referrer, document title, screen dimensions, and UTM parameters. It monkey-patches history.pushState and history.replaceState to auto-track SPA route changes.
Conversion Tracking: When you call track('event_name', meta), the SDK fires a POST to /sdk/track. If a CPA campaign exists with a matching event, Clocsy processes the conversion and credits the referrer.
Identity Linking: identify() fires a POST to /sdk/identify to link the current anonymous session to a known user. This prevents duplicate affiliate payouts across devices.

Published

Vulnerabilities

Links

Maintainers

Keywords

Readme

@clocsy/track

Why

Install

Quick Start

Framework Examples

React (Vite / CRA)

Next.js App Router

Next.js Pages Router

Vue 3

Nuxt 3

API Reference

init(config: ClocsyConfig): void

track(event: string, meta?: TrackMeta): void

identify(identity: string, meta?: IdentifyMeta): void

pageview(): void

SSR Safety

How It Works

Bundle Size

Requirements

License

`init(config: ClocsyConfig): void`

`track(event: string, meta?: TrackMeta): void`

`identify(identity: string, meta?: IdentifyMeta): void`

`pageview(): void`