taapit-sdk
v1.0.4
Published
Taapit Conversion Tracking SDK - Track leads and sales from your short links
Maintainers
qhoarauReadme
taapit-sdk
Official Taapit SDK for conversion tracking. Track leads and sales from your short links.
Installation
npm install taapit-sdk
# or
yarn add taapit-sdk
# or
pnpm add taapit-sdkQuick Start
Server-Side (Node.js)
Use this for secure, server-side tracking that can't be blocked by ad blockers.
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: '[email protected]',
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',
});React (Client-Side) - Recommended
For React applications with client-side tracking. Just add the Analytics component - no provider wrapper needed!
// app/layout.tsx
import { Analytics } from 'taapit-sdk/react';
export default function RootLayout({ children }) {
return (
<html>
<body>
{children}
<Analytics publishableKey="taapit_pk_xxx" />
</body>
</html>
);
}// 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 <form onSubmit={handleSubmit}>...</form>;
}// Option 2: Use the global taapit object (works anywhere)
import { taapit } from 'taapit-sdk/react';
function handleSignUp(userId: string) {
taapit.trackLead({
customer: { externalId: userId },
});
}React (Provider-based) - Legacy
If you prefer the provider pattern:
import { TaapitProvider, useTaapit } from 'taapit-sdk/react';
// In layout
<TaapitProvider publishableKey="taapit_pk_xxx">
{children}
</TaapitProvider>
// In components
const { trackLead } = useTaapit();Vanilla JavaScript (Browser)
For non-React websites.
<script src="https://unpkg.com/taapit-sdk/dist/browser/index.js"></script>
<script>
// Configure with your publishable key
taapit.configure({ publishableKey: 'taapit_pk_xxx' });
// Track lead
document.getElementById('signup-form').addEventListener('submit', (e) => {
taapit.trackLead({
customer: {
externalId: 'user_123',
email: '[email protected]',
},
eventName: 'Sign up',
});
});
// Track sale
taapit.trackSale({
customer: { externalId: 'user_123' },
amount: 2999,
currency: 'eur',
});
</script>Or with ES modules:
import { taapit } from 'taapit-sdk/browser';
taapit.configure({ publishableKey: 'taapit_pk_xxx' });
taapit.trackLead({ customer: { externalId: 'user_123' } });API Reference
Taapit (Server-Side)
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 conversiontaapit.track.sale(params)- Track a sale conversion
Analytics (React - Recommended)
<Analytics publishableKey="taapit_pk_xxx" baseUrl="..." />Props:
| Prop | Type | Description |
|------|------|-------------|
| publishableKey | string | Publishable key (safe for client) |
| baseUrl | string | API base URL (optional) |
useTaapitAnalytics() Hook
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 |
taapit Global Object
import { taapit } from 'taapit-sdk/react';
taapit.isReady; // boolean
taapit.trackingId; // string | undefined
taapit.trackLead(data);
taapit.trackSale(data);TaapitProvider (React - Legacy)
<TaapitProvider publishableKey="taapit_pk_xxx">
{children}
</TaapitProvider>useTaapit() Hook (Legacy)
const { isLoaded, trackingId, trackLead, trackSale } = useTaapit();Track Lead Parameters
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<string, unknown>;
}Track Sale Parameters
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<string, unknown>;
}How Tracking Works
- User clicks a Taapit link → Landing page URL includes
?ta_tid=xxx - SDK stores tracking ID → Saved to
ta_tidcookie (365 days) - User converts → You call
trackLead()ortrackSale() - 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:
import type {
TaapitConfig,
TaapitCustomer,
TrackLeadParams,
TrackSaleParams,
} from 'taapit-sdk';License
MIT