getu-attribution-v2-sdk 0.3.1 → 0.3.2

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
@@ -317,6 +318,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)**

package/dist/core/AttributionSDK.d.ts

@@ -0,0 +1,129 @@
+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): 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":"AAAA,OAAO,EACL,SAAS,EAET,SAAS,EACT,eAAe,EAEf,QAAQ,EACR,WAAW,EAGX,UAAU,EAEX,MAAM,UAAU,CAAC;AAuBlB,qBAAa,cAAc;IACzB,OAAO,CAAC,MAAM,CAAY;IAC1B,OAAO,CAAC,MAAM,CAAgB;IAC9B,OAAO,CAAC,OAAO,CAA4B;IAC3C,OAAO,CAAC,UAAU,CAAkB;IACpC,OAAO,CAAC,KAAK,CAAoB;IACjC,OAAO,CAAC,OAAO,CAA4B;IAC3C,OAAO,CAAC,WAAW,CAAkB;IACrC,OAAO,CAAC,gBAAgB,CAAkB;IAC1C,OAAO,CAAC,kBAAkB,CAAkC;IAC5D,OAAO,CAAC,cAAc,CAAuB;IAC7C,OAAO,CAAC,oBAAoB,CAAuC;IACnE,OAAO,CAAC,wBAAwB,CAAkB;IAElD,OAAO,CAAC,kBAAkB,CAAkB;IAC5C,OAAO,CAAC,eAAe,CAAc;IACrC,OAAO,CAAC,iBAAiB,CAAyC;IAClE,OAAO,CAAC,oBAAoB,CAA4C;IACxE,OAAO,CAAC,eAAe,CAAiD;gBAE5D,MAAM,EAAE,SAAS;IA+CvB,IAAI,IAAI,OAAO,CAAC,IAAI,CAAC;IAqFrB,UAAU,CACd,SAAS,EAAE,SAAS,EACpB,SAAS,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,EAC/B,gBAAgB,CAAC,EAAE,MAAM,EACzB,OAAO,CAAC,EAAE,MAAM,EAChB,QAAQ,GAAE,QAAuB,GAChC,OAAO,CAAC,IAAI,CAAC;IAqDV,aAAa,CACjB,QAAQ,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,EAC9B,gBAAgB,CAAC,EAAE,MAAM,GACxB,OAAO,CAAC,IAAI,CAAC;IAoChB,OAAO,CAAC,yBAAyB;IASjC,OAAO,CAAC,qBAAqB;YAmBf,aAAa;IAsBrB,aAAa,CACjB,gBAAgB,EAAE,MAAM,EACxB,OAAO,EAAE,MAAM,EACf,QAAQ,GAAE,QAAuB,EACjC,YAAY,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,GACjC,OAAO,CAAC,IAAI,CAAC;IAWV,UAAU,CACd,gBAAgB,EAAE,MAAM,EACxB,SAAS,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,GAC9B,OAAO,CAAC,IAAI,CAAC;IAKV,WAAW,CACf,gBAAgB,EAAE,MAAM,EACxB,UAAU,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,GAC/B,OAAO,CAAC,IAAI,CAAC;IAKV,eAAe,CACnB,gBAAgB,CAAC,EAAE,MAAM,EACzB,QAAQ,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,GAC7B,OAAO,CAAC,IAAI,CAAC;IAKV,cAAc,CAClB,gBAAgB,CAAC,EAAE,MAAM,EACzB,SAAS,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,GAC9B,OAAO,CAAC,IAAI,CAAC;IAKV,sBAAsB,CAC1B,gBAAgB,EAAE,MAAM,EACxB,gBAAgB,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,GACrC,OAAO,CAAC,IAAI,CAAC;IASV,kBAAkB,CACtB,gBAAgB,EAAE,MAAM,EACxB,SAAS,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,GAC9B,OAAO,CAAC,IAAI,CAAC;IASV,iBAAiB,CAAC,OAAO,EAAE;QAC/B,OAAO,EAAE,MAAM,CAAC;QAChB,QAAQ,CAAC,EAAE,QAAQ,CAAC;QACpB,YAAY,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,CAAC;QACnC,gBAAgB,CAAC,EAAE,MAAM,CAAC;KAC3B,GAAG,OAAO,CAAC,IAAI,CAAC;IAkBX,cAAc,CAAC,OAAO,EAAE;QAC5B,SAAS,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,CAAC;QAChC,gBAAgB,CAAC,EAAE,MAAM,CAAC;KAC3B,GAAG,OAAO,CAAC,IAAI,CAAC;IAYX,eAAe,CAAC,OAAO,EAAE;QAC7B,UAAU,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,CAAC;QACjC,gBAAgB,CAAC,EAAE,MAAM,CAAC;KAC3B,GAAG,OAAO,CAAC,IAAI,CAAC;IAYX,0BAA0B,CAAC,OAAO,EAAE;QACxC,gBAAgB,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,CAAC;QACvC,gBAAgB,CAAC,EAAE,MAAM,CAAC;KAC3B,GAAG,OAAO,CAAC,IAAI,CAAC;IAgBX,gBAAgB,CACpB,gBAAgB,CAAC,EAAE,MAAM,EACzB,WAAW,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,GAChC,OAAO,CAAC,IAAI,CAAC;IASV,cAAc,CAClB,gBAAgB,CAAC,EAAE,MAAM,EACzB,QAAQ,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,GAC7B,OAAO,CAAC,IAAI,CAAC;IAKV,cAAc,CAClB,gBAAgB,CAAC,EAAE,MAAM,EACzB,SAAS,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,GAC9B,OAAO,CAAC,IAAI,CAAC;IAKV,gBAAgB,CACpB,UAAU,CAAC,EAAE,MAAM,EACnB,gBAAgB,CAAC,EAAE,MAAM,EACzB,SAAS,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,GAC9B,OAAO,CAAC,IAAI,CAAC;IAShB,kBAAkB,IAAI,eAAe,GAAG,IAAI;IAK5C,WAAW,CAAC,GAAG,EAAE,MAAM,GAAG,MAAM;IAmBhC,mBAAmB,IAAI,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC;IAa7C,OAAO,CAAC,YAAY;IAgDpB,OAAO,CAAC,gBAAgB;IAqBxB,SAAS,CAAC,MAAM,EAAE,MAAM,GAAG,IAAI;IAW/B,SAAS,IAAI,MAAM,GAAG,IAAI;IAK1B,YAAY,IAAI,IAAI;IAKpB;;;;;;;;;;;;;OAaG;IACG,QAAQ,CAAC,MAAM,EAAE,MAAM,EAAE,MAAM,CAAC,EAAE,UAAU,GAAG,OAAO,CAAC,IAAI,CAAC;IAgClE;;OAEG;IACH,aAAa,IAAI,UAAU,GAAG,IAAI;IAIlC;;OAEG;IACH,YAAY,IAAI,MAAM,GAAG,IAAI;IAK7B,OAAO,CAAC,iBAAiB;IA4BzB,OAAO,CAAC,sBAAsB;IAgD9B,OAAO,CAAC,iBAAiB;IAazB,OAAO,CAAC,iBAAiB;IAkCzB,OAAO,CAAC,mBAAmB;IAiK3B,OAAO,CAAC,eAAe;IA6BvB,OAAO,CAAC,qBAAqB;IAU7B,OAAO,CAAC,kBAAkB;IAW1B;;;;OAIG;IACH,OAAO,CAAC,iBAAiB;IAwCzB,OAAO,CAAC,iBAAiB;IAkBzB,OAAO,CAAC,oBAAoB;IAqD5B,OAAO,CAAC,oBAAoB;IAY5B,OAAO,CAAC,uBAAuB;IAa/B,OAAO,CAAC,wBAAwB;IAWhC,OAAO,CAAC,aAAa;YAwCP,kBAAkB;IAiBhC,OAAO,CAAC,cAAc;IAMtB,OAAO,CAAC,gBAAgB;IAmFxB,OAAO,CAAC,kBAAkB;IAwB1B,OAAO,CAAC,qBAAqB;IAQvB,KAAK,IAAI,OAAO,CAAC,IAAI,CAAC;IAK5B,SAAS,IAAI;QACX,WAAW,EAAE,OAAO,CAAC;QACrB,OAAO,EAAE,WAAW,GAAG,IAAI,CAAC;QAC5B,SAAS,EAAE,MAAM,CAAC;QAClB,MAAM,EAAE,OAAO,CAAC;QAChB,cAAc,EAAE;YACd,OAAO,EAAE,OAAO,CAAC;YACjB,aAAa,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;SACvC,CAAC;QACF,WAAW,EAAE;YACX,OAAO,EAAE,OAAO,CAAC;YACjB,WAAW,EAAE,MAAM,CAAC;SACrB,CAAC;KACH;IAkBD,OAAO,IAAI,IAAI;CAOhB"}