GetuAI Attribution SDK

A JavaScript SDK for tracking user attribution and conversion events in web applications.

Features

- 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

Installation

$3

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"
>
`

$3

`bash
npm install getu-attribution-sdk
`

Configuration

$3

| 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 |

$3

`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
}
`

Usage

$3

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"
>
`

$3

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"
>
`

$3

`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",
});
`

$3

#### 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
);
`

$3

`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);
`

$3

`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', ... }
// }
// }
`

Event Types

The SDK supports the following event types:

$3

- AD_IMPRESSION - Ad impression events
- AD_CLICK - Ad click events

$3

- PAGE_VIEW - Page view events
- VIDEO_PLAY - Video play events

$3

- FORM_SUBMIT - Form submission events
- EMAIL_VERIFICATION - Email verification events

$3

- LOGIN_SUCCESS - Successful login events

$3

- SIGNUP_SUCCESS - Successful signup events

$3

- PRODUCT_VIEW - Product view events
- ADD_TO_CART - Add to cart events
- PURCHASE_COMPLETE - Purchase completion events

Auto-tracking Features

The SDK provides two independent auto-tracking options:

$3

When autoTrack is enabled, the SDK automatically tracks:

- Form Interactions: Form submissions
- Link Clicks: External link clicks with automatic UTM parameter passing

$3

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

Cross-Domain UTM Passing

The SDK automatically adds UTM parameters to external links to maintain attribution tracking across domains:

$3

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

$3

`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
});
`

$3

`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', ... }
`

$3

If a user visits your site with ?utm_source=google&utm_medium=cpc&utm_campaign=summer_sale,
and then clicks a link to https://partner-site.com/product, the SDK will automatically
modify the link to:
https://partner-site.com/product?utm_source=google&utm_medium=cpc&utm_campaign=summer_sale

Storage

The SDK uses two storage mechanisms:

$3

- Stores UTM attribution data
- Stores user session information
- 30-day retention period
- ~5MB storage limit

$3

- Stores event queue for offline processing
- Up to ~100MB storage
- 7-day cleanup for old events
- Automatic retry on connection restore

Offline Support

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

Error Handling

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
}
`

Debug Mode

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,
});
`

Advanced Usage

$3

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();
`

$3

`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);
`

$3

`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();
`

$3

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();
`

API Reference

$3

#### 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).

$3

#### trackEvent(eventType: EventType, eventData?: Record, tracking_user_id?: string, revenue?: number, currency?: Currency): Promise

Track a custom event.

#### trackPageView(pageData?: Record, tracking_user_id?:string): Promise

Track a page view event.

#### trackPurchase(tracking_user_id: string, revenue: number, currency?: Currency, purchaseData?: Record): Promise

Track a purchase event.

#### trackLogin(tracking_user_id: string, loginData?: Record): Promise

Track a login event.

#### trackSignup(tracking_user_id: string, signupData?: Record): Promise

Track a signup event.

#### trackFormSubmit(tracking_user_id?: string, formData?: Record): Promise

Track a form submission event.

$3

#### 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.

$3

#### 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.

Browser Support

- Chrome 50+
- Firefox 50+
- Safari 10+
- Edge 79+

TypeScript

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,
};
``