GetuAI Attribution SDK for client-side tracking
npm install getu-attribution-sdkA JavaScript SDK for tracking user attribution and conversion events in web applications.
- Automatic UTM Parameter Tracking: Automatically captures and stores UTM parameters from URLs
- Cross-Domain UTM Passing: Automatically adds UTM parameters to external links for seamless attribution tracking
- Event Queue Management: Batches events and sends them efficiently to the server
- Offline Support: Stores events locally when offline and syncs when connection is restored
- Auto-tracking: Automatically tracks page views, form interactions
- Immediate Event Processing: Critical events like purchases and logins are sent immediately
- Session Management: Tracks user sessions and maintains user identity
- TypeScript Support: Full TypeScript support with type definitions
Add the script tag to your HTML:
``html`
src="https://unpkg.com/getu-attribution-sdk@0.2.4/dist/getuai-attribution.min.js"
data-api-key="your_api_key_here"
>
`bash`
npm install getu-attribution-sdk
| Attribute | Type | Default | Description |
| --------------------------- | ------- | --------------------------------------------- | ----------------------------------------------- |
| data-api-key | string | required | Your GetuAI API key |data-api-endpoint
| | string | https://attribution.getu.ai/attribution/api | API endpoint URL |data-debug
| | boolean | false | Enable debug logging |data-auto-track
| | boolean | false | Enable automatic event tracking |data-auto-track-page-view
| | boolean | false | Automatically track page view on initialization |data-batch-size
| | number | 100 | Number of events to batch |data-batch-interval
| | number | 5000 | Batch interval in milliseconds |data-auto-clean-utm
| | boolean | true | Remove UTM params from URL after capture |
`typescript`
interface SDKConfig {
apiKey: string;
apiEndpoint?: string;
batchSize?: number;
batchInterval?: number;
maxRetries?: number;
retryDelay?: number;
enableDebug?: boolean;
autoTrack?: boolean;
// Control whether to automatically track page views on initialization
autoTrackPageView?: boolean;
sessionTimeout?: number;
// Cross-domain UTM tracking configuration
enableCrossDomainUTM?: boolean;
crossDomainUTMParams?: string[]; // Which UTM params to pass
excludeDomains?: string[]; // Domains to exclude from UTM passing
// Remove UTM params from URL after capture
autoCleanUTM?: boolean; // default true
}
The SDK automatically initializes when loaded with a valid API key:
`html`
src="https://unpkg.com/getu-attribution-sdk@0.2.4/dist/getuai-attribution.min.js"
data-api-key="your_api_key_here"
>
To automatically track page views when the SDK initializes:
`html`
src="https://unpkg.com/getu-attribution-sdk@0.2.4/dist/getuai-attribution.min.js"
data-api-key="your_api_key_here"
data-auto-track-page-view="true"
>
`javascript
import { init, trackEvent, EventType } from "getu-attribution-sdk";
// Initialize SDK with auto page view tracking
await init({
apiKey: "your_api_key_here",
autoTrack: true,
autoTrackPageView: true, // Automatically track page view on initialization
});
// Track custom event
await trackEvent(EventType.PAGE_VIEW, {
page: "/home",
referrer: "google.com",
});
`
#### Page Views
`javascript`
// Automatic (when autoTrack is enabled)
// Manual tracking
await trackPageView(
{
page: "/product/123",
category: "electronics",
},
"track_user_id"
);
#### Purchases
`javascript`
await trackPurchase("user_123", 99.99, Currency.USD, {
product_id: "prod_123",
category: "electronics",
quantity: 1,
});
#### Logins
`javascript`
await trackLogin("user_123", {
method: "email",
provider: "google",
});
#### Signups
`javascript`
await trackSignup("user_123", {
method: "email",
provider: "google",
});
#### Form Submissions
`javascript`
await trackFormSubmit("user_123", {
form_id: "contact_form",
form_type: "contact",
});
#### Custom Events
`javascript`
await trackEvent(
EventType.ADD_TO_CART,
{
product_id: "prod_123",
price: 29.99,
quantity: 2,
},
"user_123",
29.99,
Currency.USD
);
`javascript
import { getAttributionData } from "getu-attribution-sdk";
// Get UTM attribution data
const attribution = getAttributionData();
console.log("First touch:", attribution.firstTouch);
console.log("Last touch:", attribution.lastTouch);
console.log("Touchpoints:", attribution.touchpoints);
`
`javascript
import { getStatus } from "getu-attribution-sdk";
const status = getStatus();
console.log("SDK Status:", status);
// {
// initialized: true,
// session: { sessionId: '...', ... },
// queueSize: 5,
// online: true,
// crossDomainUTM: {
// enabled: true,
// currentParams: { utm_source: 'google', ... }
// }
// }
`
The SDK supports the following event types:
- AD_IMPRESSION - Ad impression eventsAD_CLICK
- - Ad click events
- PAGE_VIEW - Page view eventsVIDEO_PLAY
- - Video play events
- FORM_SUBMIT - Form submission eventsEMAIL_VERIFICATION
- - Email verification events
- LOGIN_SUCCESS - Successful login events
- SIGNUP_SUCCESS - Successful signup events
- PRODUCT_VIEW - Product view eventsADD_TO_CART
- - Add to cart eventsPURCHASE_COMPLETE
- - Purchase completion events
The SDK provides two independent auto-tracking options:
When autoTrack is enabled, the SDK automatically tracks:
- Form Interactions: Form submissions
- Link Clicks: External link clicks with automatic UTM parameter passing
When autoTrackPageView is enabled, the SDK automatically tracks:
- Page Views: Automatically tracks a page view event when the SDK initializes
- Independent Control: This is separate from the general autoTrack setting, allowing you to control page view tracking independently
The SDK automatically adds UTM parameters to external links to maintain attribution tracking across domains:
When a user clicks an external link, the SDK automatically:
1. Detects if the link is to a different domain
2. Checks if the domain should be excluded
3. Adds current UTM parameters to the URL
4. Tracks the enhanced link click
`javascript`
// Enable cross-domain UTM passing, default is enableCrossDomainUTM = true
await init({
apiKey: "your_api_key_here",
enableCrossDomainUTM: true,
crossDomainUTMParams: ["utm_source", "utm_medium", "utm_campaign"],
excludeDomains: ["google.com", "facebook.com"], // Exclude specific domains
});
`javascript
// Get SDK instance
const sdk = window.getuaiSDK;
// Manually add UTM parameters to any URL
const enhancedURL = sdk.addUTMToURL("https://example.com/page");
// Get current UTM parameters
const utmParams = sdk.getCurrentUTMParams();
console.log(utmParams); // { utm_source: 'google', utm_medium: 'cpc', ... }
`
If a user visits your site with ?utm_source=google&utm_medium=cpc&utm_campaign=summer_sale,https://partner-site.com/product
and then clicks a link to , the SDK will automaticallyhttps://partner-site.com/product?utm_source=google&utm_medium=cpc&utm_campaign=summer_sale
modify the link to:
The SDK uses two storage mechanisms:
- Stores UTM attribution data
- Stores user session information
- 30-day retention period
- ~5MB storage limit
- Stores event queue for offline processing
- Up to ~100MB storage
- 7-day cleanup for old events
- Automatic retry on connection restore
The SDK automatically handles offline scenarios:
1. Events are queued in IndexedDB when offline
2. Events are sent when connection is restored
3. Failed requests are retried with exponential backoff
4. Critical events (purchases, logins) are sent immediately when possible
The SDK includes comprehensive error handling:
`javascript`
try {
await trackEvent(
EventType.PURCHASE_COMPLETE,
{ amount: 99.99 },
"user_123",
99.99
);
} catch (error) {
console.error("Failed to track purchase:", error);
// Event will be queued for retry
}
Enable debug mode to see detailed logs:
`html`
src="https://unpkg.com/getu-attribution-sdk@0.2.4/dist/getuai-attribution.min.js"
data-api-key="your_api_key_here"
data-debug="true"
>
Or programmatically:
`javascript`
await init({
apiKey: "your_api_key_here",
enableDebug: true,
});
You can use static methods directly on the AttributionSDK class:
`javascript
// Initialize SDK
await AttributionSDK.init({
apiKey: "your_api_key_here",
autoTrack: true,
autoTrackPageView: true, // Automatically track page view on initialization
});
// Track events using static methods
await AttributionSDK.trackEvent(
EventType.PURCHASE_COMPLETE,
{ product_id: "123" },
"user_123",
99.99
);
await AttributionSDK.trackPageView();
await AttributionSDK.trackPurchase("user_123", 99.99);
await AttributionSDK.trackLogin("user_123", { method: "email" });
await AttributionSDK.trackSignup("user_123", { method: "email" });
// Get attribution data
const attributionData = AttributionSDK.getAttributionData();
// Add UTM to URL
const enhancedURL = AttributionSDK.addUTMToURL("https://example.com");
// Get current UTM parameters
const utmParams = AttributionSDK.getCurrentUTMParams();
// Flush pending events
await AttributionSDK.flush();
// Get SDK status
const status = AttributionSDK.getStatus();
// Destroy SDK
AttributionSDK.destroy();
`
`javascript
import { AttributionSDK } from "getu-attribution-sdk";
const sdk = new AttributionSDK({
apiKey: "your_api_key_here",
enableDebug: true,
autoTrackPageView: true, // Automatically track page view on initialization
});
await sdk.init();
await sdk.trackEvent(EventType.PAGE_VIEW);
`
`javascript
import { init, trackEvent, flush, destroy } from "getu-attribution-sdk";
// Initialize SDK
await init({
apiKey: "your_api_key_here",
enableDebug: true,
autoTrackPageView: true, // Automatically track page view on initialization
});
// Track events
await trackEvent(
EventType.PURCHASE_COMPLETE,
{ product_id: "123" },
"user_123",
99.99
);
// Flush events
await flush();
// Destroy SDK
destroy();
`
When using the CDN version, all functions are available on the global window object:
`javascript
// Initialize SDK
await window.getuaiSDK.init({
apiKey: "your_api_key_here",
enableDebug: true,
autoTrackPageView: true, // Automatically track page view on initialization
});
// Track events
await window.getuaiSDK.trackEvent(
window.getuaiSDK.EventType.PURCHASE_COMPLETE,
{ product_id: "123" },
"user_123",
99.99
);
// Get attribution data
const attribution = window.getuaiSDK.getAttributionData();
// Add UTM to URL
const enhancedURL = window.getuaiSDK.addUTMToURL("https://example.com");
// Get current UTM parameters
const utmParams = window.getuaiSDK.getCurrentUTMParams();
// Flush events
await window.getuaiSDK.flush();
// Get status
const status = window.getuaiSDK.getStatus();
// Destroy SDK
window.getuaiSDK.destroy();
`
#### init(config: SDKConfig): Promise
Initialize the SDK with configuration.
#### getSDK(): AttributionSDK | null
Get the current SDK instance.
#### waitForSDK(): Promise
Wait for the SDK to be ready (useful when using auto-initialization).
#### trackEvent(eventType: EventType, eventData?: Record
Track a custom event.
#### trackPageView(pageData?: Record
Track a page view event.
#### trackPurchase(tracking_user_id: string, revenue: number, currency?: Currency, purchaseData?: Record
Track a purchase event.
#### trackLogin(tracking_user_id: string, loginData?: Record
Track a login event.
#### trackSignup(tracking_user_id: string, signupData?: Record
Track a signup event.
#### trackFormSubmit(tracking_user_id?: string, formData?: Record
Track a form submission event.
#### getAttributionData(): AttributionData | null
Get the current attribution data including first touch, last touch, and touchpoints.
#### addUTMToURL(url: string): string
Add current UTM parameters to a URL.
#### getCurrentUTMParams(): Record
Get the current UTM parameters.
#### flush(): Promise
Flush all pending events to the server.
#### getStatus(): SDKStatus | null
Get the current SDK status including initialization state, session info, queue size, and online status.
#### destroy(): void
Destroy the SDK instance and clean up resources.
- Chrome 50+
- Firefox 50+
- Safari 10+
- Edge 79+
The SDK includes full TypeScript support:
`typescript
import {
init,
trackEvent,
EventType,
Currency,
type SDKConfig,
type EventData,
type AttributionData,
} from "getu-attribution-sdk";
const config: SDKConfig = {
apiKey: "your_api_key_here",
enableDebug: true,
};
await init(config);
const eventData: Partial
event_type: EventType.PURCHASE_COMPLETE,
revenue: 99.99,
currency: Currency.USD,
};
``