taapit-sdk

Official Taapit SDK for conversion tracking. Track leads and sales from your short links.

Installation

``bash
npm install taapit-sdk

or

yarn add taapit-sdk

or

pnpm add taapit-sdk
`

Quick Start

$3

Use this for secure, server-side tracking that can't be blocked by ad blockers.

`typescript
import { Taapit } from 'taapit-sdk';

const taapit = new Taapit({
apiKey: process.env.TAAPIT_API_KEY, // Secret API key (never expose!)
});

// Get tracking ID from cookie (ta_tid)
const trackingId = req.cookies['ta_tid'];

// Track a lead (e.g., after user sign up)
await taapit.track.lead({
trackingId,
customer: {
externalId: 'user_123',
email: 'user@example.com',
name: 'John Doe',
},
eventName: 'Sign up',
metadata: { source: 'landing-page' },
});

// Track a sale (e.g., after purchase)
await taapit.track.sale({
trackingId,
customer: { externalId: 'user_123' },
amount: 2999, // Amount in cents (29.99)
currency: 'eur',
invoiceId: 'inv_123',
});
`

$3

For React applications with client-side tracking. Just add the Analytics component - no provider wrapper needed!

`tsx
// app/layout.tsx
import { Analytics } from 'taapit-sdk/react';

export default function RootLayout({ children }) {
return (


{children}



);
}
`

`tsx
// In your components - Option 1: Use the hook
import { useTaapitAnalytics } from 'taapit-sdk/react';

function SignUpForm() {
const { trackLead, isReady, trackingId } = useTaapitAnalytics();

const handleSubmit = async (formData) => {
const user = await createUser(formData);

trackLead({
customer: { externalId: user.id, email: formData.email },
});
};

return

...

;
}
`

`tsx
// Option 2: Use the global taapit object (works anywhere)
import { taapit } from 'taapit-sdk/react';

function handleSignUp(userId: string) {
taapit.trackLead({
customer: { externalId: userId },
});
}
`

$3

If you prefer the provider pattern:

`tsx
import { TaapitProvider, useTaapit } from 'taapit-sdk/react';

// In layout

{children}


// In components
const { trackLead } = useTaapit();
`

$3

For non-React websites.

`html


`

Or with ES modules:

`typescript
import { taapit } from 'taapit-sdk/browser';

taapit.configure({ publishableKey: 'taapit_pk_xxx' });
taapit.trackLead({ customer: { externalId: 'user_123' } });
`

API Reference

$3

`typescript
const taapit = new Taapit(config);
`

Config Options:
| Option | Type | Description |
|--------|------|-------------|
| apiKey | string | Secret API key (from dashboard) |
| baseUrl | string | API base URL (default: https://api.taap.it) |

Methods:
- taapit.track.lead(params) - Track a lead conversion
- taapit.track.sale(params) - Track a sale conversion

$3

`tsx

`

Props:
| Prop | Type | Description |
|------|------|-------------|
| publishableKey | string | Publishable key (safe for client) |
| baseUrl | string | API base URL (optional) |

$3

`typescript
const { isReady, trackingId, trackLead, trackSale } = useTaapitAnalytics();
`

Returns:
| Property | Type | Description |
|----------|------|-------------|
| isReady | boolean | SDK initialized |
| trackingId | string \| undefined | Current tracking ID |
| trackLead | function | Track lead event |
| trackSale | function | Track sale event |

$3

`typescript
import { taapit } from 'taapit-sdk/react';

taapit.isReady; // boolean
taapit.trackingId; // string | undefined
taapit.trackLead(data);
taapit.trackSale(data);
`

$3

`tsx

{children}

`

$3

`typescript
const { isLoaded, trackingId, trackLead, trackSale } = useTaapit();
`

$3

`typescript
interface TrackLeadParams {
trackingId?: string; // Auto-detected in client SDK
customer: {
externalId: string; // Required: Your internal user ID
email?: string;
firstname?: string;
lastname?: string;
phoneNumber?: string;
avatarUrl?: string;
};
metadata?: Record;
}
`

$3

`typescript
interface TrackSaleParams {
trackingId?: string; // Auto-detected in client SDK
customer: {
externalId: string; // Required: Your internal user ID
email?: string;
firstname?: string;
lastname?: string;
phoneNumber?: string;
avatarUrl?: string;
};
amount: number; // Amount in cents (2999 = 29.99)
currency: string; // e.g., "eur", "usd"
metadata?: Record;
}
`

How Tracking Works

1. User clicks a Taapit link → Landing page URL includes ?ta_tid=xxx
2. SDK stores tracking ID → Saved to ta_tid cookie (365 days)
3. User converts → You call trackLead() or trackSale()
4. Attribution recorded → Conversion linked to original link click

Security

- API Key (TAAPIT_API_KEY): Secret, server-side only. Never expose in client code.
- Publishable Key (taapit_pk_xxx): Safe for client-side. Can only send events, not read data.

TypeScript Support

Full TypeScript support with exported types:

`typescript
import type {
TaapitConfig,
TaapitCustomer,
TrackLeadParams,
TrackSaleParams,
} from 'taapit-sdk';
``

License

MIT