getu-attribution-v2-sdk 0.3.1 → 0.3.3

package/README.md

@@ -253,6 +253,7 @@ enum EventType {
   // Pre-conversion signals
   PAGE_VIEW = "page_view",
   PAGE_CLICK = "page_click",
+  BUTTON_CLICK = "button_click",
   VIDEO_PLAY = "video_play",
 
   // Registration funnel
@@ -272,6 +273,9 @@ enum EventType {
 
   // Post-conversion / back-office conversion
   AUDIT_APPROVED = "audit_approved",
+
+  // User-defined custom events
+  CUSTOM = "custom",
 }
 ```
 
@@ -317,6 +321,28 @@ await trackPageClick("user_123", {
 });
 ```
 
+### Track Button Click
+
+```javascript
+// Basic - button name only
+await trackButtonClick("Sign Up");
+
+// With user ID
+await trackButtonClick("Buy Now", "user_123");
+
+// With extra data
+await trackButtonClick("Download Report", "user_123", {
+  section: "hero",
+  page: "/pricing",
+  variant: "primary",
+});
+
+// Without button name (anonymous click)
+await trackButtonClick();
+```
+
+The event will be sent with `event_data.button_name` set to the provided name.
+
 ### Track Purchase
 
 **Method 1: Traditional format (user_id required)**
@@ -541,21 +567,32 @@ await trackAddToCart("user_123", {
 
 ### Track Custom Event
 
+Use `trackCustomEvent` to track any user-defined event with a custom name. The event name is required and must be non-empty.
+
 ```javascript
-await trackEvent(
-  EventType.ADD_TO_CART,
-  {
-    product_id: "prod_123",
-    product_name: "Widget",
-    price: 29.99,
-    quantity: 2,
-  },
+// Basic - event name only
+await trackCustomEvent("webinar_registered");
+
+// With custom data
+await trackCustomEvent("webinar_registered", {
+  webinar_id: "webinar_123",
+  webinar_title: "Advanced Analytics",
+});
+
+// With user ID and revenue
+await trackCustomEvent(
+  "subscription_upgraded",
+  { plan: "pro", billing_cycle: "annual" },
   "user_123", // tracking_user_id (optional)
-  29.99, // revenue (optional)
-  Currency.USD // currency (optional)
+  299.00,     // revenue (optional)
+  Currency.USD // currency (optional, default: USD)
 );
 ```
 
+Custom events are **batched** (not sent immediately). Use `flush()` to force-send pending events.
+
+**Validation**: An empty or whitespace-only event name will be rejected client-side with a console error.
+
 ---
 
 ## Auto-Tracking
@@ -887,6 +924,27 @@ await trackAddToCart("user_123", {
 });
 ```
 
+#### `trackCustomEvent(customEventName, eventData?, tracking_user_id?, revenue?, currency?): Promise<void>`
+
+Track a user-defined custom event. The `customEventName` is required and must be a non-empty string.
+
+| Parameter | Type | Required | Description |
+|-----------|------|----------|-------------|
+| `customEventName` | string | **Yes** | Event name (e.g. `"webinar_registered"`) |
+| `eventData` | object | No | Arbitrary key-value payload |
+| `tracking_user_id` | string | No | User identifier; falls back to stored user ID |
+| `revenue` | number | No | Revenue amount |
+| `currency` | Currency | No | Currency code (default: `Currency.USD`) |
+
+```javascript
+await trackCustomEvent("feature_used", {
+  feature: "export_csv",
+  records_count: 500,
+});
+```
+
+Custom events are **batched**. Call `flush()` to force immediate delivery.
+
 ### Attribution Functions
 
 #### `getAttributionData(): AttributionData | null`

package/dist/core/AttributionSDK.d.ts

@@ -0,0 +1,130 @@
+import { SDKConfig, EventType, AttributionData, Currency, UserSession, UserTraits } from "../types";
+export declare class AttributionSDK {
+    private config;
+    private logger;
+    private storage;
+    private httpClient;
+    private queue;
+    private session;
+    private initialized;
+    private autoTrackEnabled;
+    private pageViewTrackTimes;
+    private cachedPublicIP;
+    private publicIPFetchPromise;
+    private initialPageViewTriggered;
+    private spaTrackingEnabled;
+    private lastTrackedPath;
+    private originalPushState;
+    private originalReplaceState;
+    private popstateHandler;
+    constructor(config: SDKConfig);
+    init(): Promise<void>;
+    trackEvent(eventType: EventType, eventData?: Record<string, any>, tracking_user_id?: string, revenue?: number, currency?: Currency, custom_event_name?: string): Promise<void>;
+    trackCustomEvent(customEventName: string, eventData?: Record<string, any>, tracking_user_id?: string, revenue?: number, currency?: Currency): Promise<void>;
+    trackPageView(pageData?: Record<string, any>, tracking_user_id?: string): Promise<void>;
+    private cleanupPageViewTrackTimes;
+    private ensurePublicIPFetched;
+    private fetchPublicIP;
+    trackPurchase(tracking_user_id: string, revenue: number, currency?: Currency, purchaseData?: Record<string, any>): Promise<void>;
+    trackLogin(tracking_user_id: string, loginData?: Record<string, any>): Promise<void>;
+    trackSignup(tracking_user_id: string, signupData?: Record<string, any>): Promise<void>;
+    trackFormSubmit(tracking_user_id?: string, formData?: Record<string, any>): Promise<void>;
+    trackVideoPlay(tracking_user_id?: string, videoData?: Record<string, any>): Promise<void>;
+    trackEmailVerification(tracking_user_id: string, verificationData?: Record<string, any>): Promise<void>;
+    trackAuditApproved(tracking_user_id: string, auditData?: Record<string, any>): Promise<void>;
+    trackPurchaseAuto(options: {
+        revenue: number;
+        currency?: Currency;
+        purchaseData?: Record<string, any>;
+        tracking_user_id?: string;
+    }): Promise<void>;
+    trackLoginAuto(options: {
+        loginData?: Record<string, any>;
+        tracking_user_id?: string;
+    }): Promise<void>;
+    trackSignupAuto(options: {
+        signupData?: Record<string, any>;
+        tracking_user_id?: string;
+    }): Promise<void>;
+    trackEmailVerificationAuto(options: {
+        verificationData?: Record<string, any>;
+        tracking_user_id?: string;
+    }): Promise<void>;
+    trackProductView(tracking_user_id?: string, productData?: Record<string, any>): Promise<void>;
+    trackAddToCart(tracking_user_id?: string, cartData?: Record<string, any>): Promise<void>;
+    trackPageClick(tracking_user_id?: string, clickData?: Record<string, any>): Promise<void>;
+    trackButtonClick(buttonName?: string, tracking_user_id?: string, clickData?: Record<string, any>): Promise<void>;
+    getAttributionData(): AttributionData | null;
+    addUTMToURL(url: string): string;
+    getCurrentUTMParams(): Record<string, string>;
+    private getUTMParams;
+    private initializeUserId;
+    setUserId(userId: string): void;
+    getUserId(): string | null;
+    removeUserId(): void;
+    /**
+     * Identify user and set user attributes
+     * Used to explicitly set user information, e.g., after login
+     *
+     * @param userId User unique identifier
+     * @param traits User attributes
+     *
+     * @example
+     * sdk.identify('user-123', {
+     *   email: 'user@example.com',
+     *   name: 'John Doe',
+     *   company_name: 'Acme Inc'
+     * });
+     */
+    identify(userId: string, traits?: UserTraits): Promise<void>;
+    /**
+     * Get current user traits
+     */
+    getUserTraits(): UserTraits | null;
+    /**
+     * Get current session ID
+     */
+    getSessionId(): string | null;
+    private initializeSession;
+    private extractAndStoreUTMData;
+    private setupAutoTracking;
+    private setupFormTracking;
+    private serializeFormFields;
+    private getFormFieldKey;
+    private normalizeFormFieldKey;
+    private serializeFormValue;
+    /**
+     * Extract standardized lead fields from form data
+     * @param formData Serialized form data
+     * @returns Extracted user traits
+     */
+    private extractLeadFields;
+    private setupLinkTracking;
+    private handleCrossDomainUTM;
+    private setupNetworkHandlers;
+    private setupVisibilityHandlers;
+    private setupBeforeUnloadHandler;
+    private flushOnUnload;
+    private retryPendingEvents;
+    private getCurrentPath;
+    private setupSPATracking;
+    private cleanupSPATracking;
+    private updateSessionActivity;
+    flush(): Promise<void>;
+    getStatus(): {
+        initialized: boolean;
+        session: UserSession | null;
+        queueSize: number;
+        online: boolean;
+        crossDomainUTM: {
+            enabled: boolean;
+            currentParams: Record<string, string>;
+        };
+        spaTracking: {
+            enabled: boolean;
+            currentPath: string;
+        };
+    };
+    destroy(): void;
+}
+//# sourceMappingURL=AttributionSDK.d.ts.map

package/dist/core/AttributionSDK.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"AttributionSDK.d.ts","sourceRoot":"","sources":["../../src/core/AttributionSDK.ts"],"names":[],"mappings":"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"}