@axyle/expo-sdk 1.0.0

package/dist/hooks/useScreenTracking.js

@@ -0,0 +1,52 @@
+"use strict";
+/**
+ * React hook for automatic screen tracking with time tracking
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.useScreenTracking = useScreenTracking;
+const react_1 = require("react");
+const core_1 = require("../core");
+/**
+ * Hook to automatically track screen views with time tracking
+ *
+ * @example
+ * ```tsx
+ * function HomeScreen() {
+ *   useScreenTracking({ screenName: 'Home' });
+ *   return <View>...</View>;
+ * }
+ * ```
+ */
+function useScreenTracking(options) {
+    const { screenName, properties = {}, trackTime = true } = options;
+    const hasTracked = (0, react_1.useRef)(false);
+    const screenStartTime = (0, react_1.useRef)(null);
+    (0, react_1.useEffect)(() => {
+        // Track screen view only once when component mounts
+        if (!hasTracked.current) {
+            const startTime = Date.now();
+            screenStartTime.current = startTime;
+            (0, core_1.track)("Screen Viewed", {
+                screen: screenName,
+                screen_start_time: startTime,
+                ...properties,
+            });
+            hasTracked.current = true;
+        }
+        // Track screen time when component unmounts
+        return () => {
+            if (trackTime && screenStartTime.current !== null) {
+                const endTime = Date.now();
+                const duration = endTime - screenStartTime.current;
+                (0, core_1.track)("Screen Time", {
+                    screen: screenName,
+                    duration_ms: duration,
+                    duration_seconds: Math.round(duration / 1000),
+                    screen_start_time: screenStartTime.current,
+                    screen_end_time: endTime,
+                    ...properties,
+                });
+            }
+        };
+    }, [screenName, properties, trackTime]);
+}

package/dist/hooks/useScrollTracking.d.ts

@@ -0,0 +1,39 @@
+/**
+ * React hook for scroll tracking
+ */
+import { ScrollView } from "react-native";
+export interface ScrollTrackingOptions {
+    /** Screen/page name where scroll is being tracked */
+    screenName: string;
+    /** Additional properties to track with scroll events */
+    properties?: Record<string, any>;
+    /** Threshold percentages to track (default: [25, 50, 75, 100]) */
+    thresholds?: number[];
+    /** Minimum scroll distance before tracking (default: 100) */
+    minScrollDistance?: number;
+}
+/**
+ * Hook to automatically track scroll depth on ScrollView
+ *
+ * @example
+ * ```tsx
+ * function ArticleScreen() {
+ *   const scrollViewRef = useScrollTracking({
+ *     screenName: 'Article',
+ *     thresholds: [25, 50, 75, 100]
+ *   });
+ *
+ *   return (
+ *     <ScrollView ref={scrollViewRef}>
+ *       {/* content *\/}
+ *     </ScrollView>
+ *   );
+ * }
+ * ```
+ */
+export declare function useScrollTracking(options: ScrollTrackingOptions): import("react").RefObject<ScrollView>;
+/**
+ * Hook for tracking scroll on web pages
+ * Use this for web/React implementations
+ */
+export declare function useWebScrollTracking(options: ScrollTrackingOptions): void;

package/dist/hooks/useScrollTracking.js

@@ -0,0 +1,146 @@
+"use strict";
+/**
+ * React hook for scroll tracking
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.useScrollTracking = useScrollTracking;
+exports.useWebScrollTracking = useWebScrollTracking;
+const react_1 = require("react");
+const core_1 = require("../core");
+/**
+ * Hook to automatically track scroll depth on ScrollView
+ *
+ * @example
+ * ```tsx
+ * function ArticleScreen() {
+ *   const scrollViewRef = useScrollTracking({
+ *     screenName: 'Article',
+ *     thresholds: [25, 50, 75, 100]
+ *   });
+ *
+ *   return (
+ *     <ScrollView ref={scrollViewRef}>
+ *       {/* content *\/}
+ *     </ScrollView>
+ *   );
+ * }
+ * ```
+ */
+function useScrollTracking(options) {
+    const { screenName, properties = {}, thresholds = [25, 50, 75, 100], minScrollDistance = 100, } = options;
+    const scrollViewRef = (0, react_1.useRef)(null);
+    const trackedThresholds = (0, react_1.useRef)(new Set());
+    const lastScrollY = (0, react_1.useRef)(0);
+    const contentHeight = (0, react_1.useRef)(0);
+    const scrollViewHeight = (0, react_1.useRef)(0);
+    (0, react_1.useEffect)(() => {
+        const scrollView = scrollViewRef.current;
+        if (!scrollView)
+            return;
+        const handleScroll = (event) => {
+            const { contentOffset, contentSize, layoutMeasurement } = event.nativeEvent;
+            const scrollY = contentOffset.y;
+            const contentHeightValue = contentSize.height;
+            const scrollViewHeightValue = layoutMeasurement.height;
+            contentHeight.current = contentHeightValue;
+            scrollViewHeight.current = scrollViewHeightValue;
+            // Calculate scroll percentage
+            const maxScroll = Math.max(0, contentHeightValue - scrollViewHeightValue);
+            if (maxScroll === 0)
+                return;
+            const scrollPercentage = Math.round((scrollY / maxScroll) * 100);
+            const scrollDistance = Math.abs(scrollY - lastScrollY.current);
+            // Only track if minimum scroll distance is met
+            if (scrollDistance < minScrollDistance)
+                return;
+            lastScrollY.current = scrollY;
+            // Track threshold milestones
+            for (const threshold of thresholds) {
+                if (scrollPercentage >= threshold &&
+                    !trackedThresholds.current.has(threshold)) {
+                    trackedThresholds.current.add(threshold);
+                    (0, core_1.track)("Scroll Depth", {
+                        screen: screenName,
+                        scroll_percentage: scrollPercentage,
+                        scroll_threshold: threshold,
+                        scroll_y: scrollY,
+                        content_height: contentHeightValue,
+                        viewport_height: scrollViewHeightValue,
+                        ...properties,
+                    });
+                }
+            }
+            // Track general scroll event periodically (every 10% scroll)
+            const scrollBucket = Math.floor(scrollPercentage / 10) * 10;
+            if (scrollBucket > 0 && scrollBucket % 10 === 0) {
+                (0, core_1.track)("Scroll Event", {
+                    screen: screenName,
+                    scroll_percentage: scrollPercentage,
+                    scroll_y: scrollY,
+                    ...properties,
+                });
+            }
+        };
+        // Note: ScrollView doesn't have a direct onScroll prop in React Native
+        // This would need to be implemented differently for React Native
+        // For web, we can use onScroll directly
+        if (scrollView && "addEventListener" in scrollView) {
+            // Web implementation
+            scrollView.addEventListener("scroll", handleScroll);
+            return () => {
+                scrollView.removeEventListener("scroll", handleScroll);
+            };
+        }
+    }, [screenName, properties, thresholds, minScrollDistance]);
+    return scrollViewRef;
+}
+/**
+ * Hook for tracking scroll on web pages
+ * Use this for web/React implementations
+ */
+function useWebScrollTracking(options) {
+    const { screenName, properties = {}, thresholds = [25, 50, 75, 100], minScrollDistance = 100, } = options;
+    const trackedThresholds = (0, react_1.useRef)(new Set());
+    const lastScrollY = (0, react_1.useRef)(0);
+    (0, react_1.useEffect)(() => {
+        const handleScroll = () => {
+            // Type guard for web environment
+            if (typeof window === "undefined" || typeof document === "undefined") {
+                return;
+            }
+            const scrollY = window.scrollY || document.documentElement.scrollTop;
+            const documentHeight = document.documentElement.scrollHeight;
+            const windowHeight = window.innerHeight;
+            const maxScroll = documentHeight - windowHeight;
+            if (maxScroll === 0)
+                return;
+            const scrollPercentage = Math.round((scrollY / maxScroll) * 100);
+            const scrollDistance = Math.abs(scrollY - lastScrollY.current);
+            if (scrollDistance < minScrollDistance)
+                return;
+            lastScrollY.current = scrollY;
+            // Track threshold milestones
+            for (const threshold of thresholds) {
+                if (scrollPercentage >= threshold &&
+                    !trackedThresholds.current.has(threshold)) {
+                    trackedThresholds.current.add(threshold);
+                    (0, core_1.track)("Scroll Depth", {
+                        screen: screenName,
+                        scroll_percentage: scrollPercentage,
+                        scroll_threshold: threshold,
+                        scroll_y: scrollY,
+                        content_height: documentHeight,
+                        viewport_height: windowHeight,
+                        ...properties,
+                    });
+                }
+            }
+        };
+        if (typeof window !== "undefined") {
+            window.addEventListener("scroll", handleScroll, { passive: true });
+            return () => {
+                window.removeEventListener("scroll", handleScroll);
+            };
+        }
+    }, [screenName, properties, thresholds, minScrollDistance]);
+}

package/dist/index.d.ts

@@ -0,0 +1,140 @@
+/**
+ * Axyle Analytics SDK
+ * Main entry point
+ */
+import type { AnalyticsEvent, AxyleInitConfig, EventContext, EventProperties, UserTraits } from "./types";
+/**
+ * Axyle - Main SDK interface
+ */
+export declare const Axyle: {
+    /**
+     * Initialize the SDK with your API key
+     *
+     * @example
+     * ```ts
+     * // Simple: just pass the API key as a string
+     * Axyle.init('your-api-key');
+     *
+     * // Or as an object
+     * Axyle.init({ apiKey: 'your-api-key' });
+     * ```
+     */
+    init: (config: AxyleInitConfig) => Promise<void>;
+    /**
+     * Track a custom event
+     *
+     * @example
+     * ```ts
+     * Axyle.track('Button Clicked', {
+     *   button: 'Sign Up',
+     *   screen: 'Home'
+     * });
+     * ```
+     */
+    track: (eventName: string, properties?: EventProperties) => Promise<void>;
+    /**
+     * Identify a user
+     *
+     * @example
+     * ```ts
+     * Axyle.identify('user-123', {
+     *   email: 'user@example.com',
+     *   plan: 'premium'
+     * });
+     * ```
+     */
+    identify: (userId: string, traits?: UserTraits) => Promise<void>;
+    /**
+     * Reset user data (call on logout)
+     *
+     * @example
+     * ```ts
+     * Axyle.reset();
+     * ```
+     */
+    reset: () => Promise<void>;
+    /**
+     * Opt out of tracking
+     *
+     * @example
+     * ```ts
+     * Axyle.optOut();
+     * ```
+     */
+    optOut: () => Promise<void>;
+    /**
+     * Opt back in to tracking
+     *
+     * @example
+     * ```ts
+     * Axyle.optIn();
+     * ```
+     */
+    optIn: () => Promise<void>;
+    /**
+     * Request user data deletion
+     *
+     * @example
+     * ```ts
+     * Axyle.deleteUser('user-123');
+     * ```
+     */
+    deleteUser: (userId: string) => Promise<void>;
+    /**
+     * Manually flush all queued events to the server
+     *
+     * @example
+     * ```ts
+     * await Axyle.flush();
+     * ```
+     */
+    flush: () => Promise<void>;
+    /**
+     * Shutdown the SDK (flushes events and cleans up resources)
+     *
+     * @example
+     * ```ts
+     * await Axyle.shutdown();
+     * ```
+     */
+    shutdown: () => Promise<void>;
+    /**
+     * Get session analytics statistics
+     *
+     * @example
+     * ```ts
+     * const stats = Axyle.getSessionStats();
+     * console.log('Total events:', stats?.totalEvents);
+     * ```
+     */
+    getSessionStats: () => import("./sessionAnalytics").SessionAnalyticsStats | null;
+    /**
+     * Get all events in current session
+     *
+     * @example
+     * ```ts
+     * const events = Axyle.getSessionEvents();
+     * ```
+     */
+    getSessionEvents: () => AnalyticsEvent[];
+    /**
+     * Get events by type in current session
+     *
+     * @example
+     * ```ts
+     * const buttonClicks = Axyle.getEventsByType('Button Clicked');
+     * ```
+     */
+    getEventsByType: (eventName: string) => AnalyticsEvent[];
+};
+export type { AnalyticsEvent, AxyleInitConfig, EventContext, EventProperties, UserTraits, };
+export type { SessionAnalyticsStats } from "./sessionAnalytics";
+export { isValidApiKeyFormat } from "./configLoader";
+export { trackFeatureUsage, trackFeatureUsageWithContext, useFeatureViewTracking, } from "./hooks/useFeatureTracking";
+export { trackFlowAbandoned, trackFlowCompleted, trackOnboardingAbandoned, trackOnboardingCompleted, useFlowTracking, useOnboardingTracking, } from "./hooks/useOnboardingTracking";
+export type { FlowTrackingOptions } from "./hooks/useOnboardingTracking";
+export { useScreenTracking } from "./hooks/useScreenTracking";
+export { useScrollTracking, useWebScrollTracking, } from "./hooks/useScrollTracking";
+export { createNavigationTracker, trackNavigationReady, trackNavigationStateChange, } from "./integrations/reactNavigation";
+export declare function trackScreen(screenName: string, properties?: Record<string, any>): void;
+export default Axyle;

package/dist/index.js

@@ -0,0 +1,171 @@
+"use strict";
+/**
+ * Axyle Analytics SDK
+ * Main entry point
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.trackNavigationStateChange = exports.trackNavigationReady = exports.createNavigationTracker = exports.useWebScrollTracking = exports.useScrollTracking = exports.useScreenTracking = exports.useOnboardingTracking = exports.useFlowTracking = exports.trackOnboardingCompleted = exports.trackOnboardingAbandoned = exports.trackFlowCompleted = exports.trackFlowAbandoned = exports.useFeatureViewTracking = exports.trackFeatureUsageWithContext = exports.trackFeatureUsage = exports.isValidApiKeyFormat = exports.Axyle = void 0;
+exports.trackScreen = trackScreen;
+const core_1 = require("./core");
+/**
+ * Axyle - Main SDK interface
+ */
+exports.Axyle = {
+    /**
+     * Initialize the SDK with your API key
+     *
+     * @example
+     * ```ts
+     * // Simple: just pass the API key as a string
+     * Axyle.init('your-api-key');
+     *
+     * // Or as an object
+     * Axyle.init({ apiKey: 'your-api-key' });
+     * ```
+     */
+    init: (config) => core_1.client.init(config),
+    /**
+     * Track a custom event
+     *
+     * @example
+     * ```ts
+     * Axyle.track('Button Clicked', {
+     *   button: 'Sign Up',
+     *   screen: 'Home'
+     * });
+     * ```
+     */
+    track: (eventName, properties) => core_1.client.track(eventName, properties),
+    /**
+     * Identify a user
+     *
+     * @example
+     * ```ts
+     * Axyle.identify('user-123', {
+     *   email: 'user@example.com',
+     *   plan: 'premium'
+     * });
+     * ```
+     */
+    identify: (userId, traits) => core_1.client.identify(userId, traits),
+    /**
+     * Reset user data (call on logout)
+     *
+     * @example
+     * ```ts
+     * Axyle.reset();
+     * ```
+     */
+    reset: () => core_1.client.reset(),
+    /**
+     * Opt out of tracking
+     *
+     * @example
+     * ```ts
+     * Axyle.optOut();
+     * ```
+     */
+    optOut: () => core_1.client.optOut(),
+    /**
+     * Opt back in to tracking
+     *
+     * @example
+     * ```ts
+     * Axyle.optIn();
+     * ```
+     */
+    optIn: () => core_1.client.optIn(),
+    /**
+     * Request user data deletion
+     *
+     * @example
+     * ```ts
+     * Axyle.deleteUser('user-123');
+     * ```
+     */
+    deleteUser: (userId) => core_1.client.deleteUser(userId),
+    /**
+     * Manually flush all queued events to the server
+     *
+     * @example
+     * ```ts
+     * await Axyle.flush();
+     * ```
+     */
+    flush: () => core_1.client.flush(),
+    /**
+     * Shutdown the SDK (flushes events and cleans up resources)
+     *
+     * @example
+     * ```ts
+     * await Axyle.shutdown();
+     * ```
+     */
+    shutdown: () => core_1.client.shutdown(),
+    /**
+     * Get session analytics statistics
+     *
+     * @example
+     * ```ts
+     * const stats = Axyle.getSessionStats();
+     * console.log('Total events:', stats?.totalEvents);
+     * ```
+     */
+    getSessionStats: () => core_1.client.getSessionStats(),
+    /**
+     * Get all events in current session
+     *
+     * @example
+     * ```ts
+     * const events = Axyle.getSessionEvents();
+     * ```
+     */
+    getSessionEvents: () => core_1.client.getSessionEvents(),
+    /**
+     * Get events by type in current session
+     *
+     * @example
+     * ```ts
+     * const buttonClicks = Axyle.getEventsByType('Button Clicked');
+     * ```
+     */
+    getEventsByType: (eventName) => core_1.client.getEventsByType(eventName),
+};
+// Export API key validation utility (still useful)
+var configLoader_1 = require("./configLoader");
+Object.defineProperty(exports, "isValidApiKeyFormat", { enumerable: true, get: function () { return configLoader_1.isValidApiKeyFormat; } });
+// Export hooks and integrations
+var useFeatureTracking_1 = require("./hooks/useFeatureTracking");
+Object.defineProperty(exports, "trackFeatureUsage", { enumerable: true, get: function () { return useFeatureTracking_1.trackFeatureUsage; } });
+Object.defineProperty(exports, "trackFeatureUsageWithContext", { enumerable: true, get: function () { return useFeatureTracking_1.trackFeatureUsageWithContext; } });
+Object.defineProperty(exports, "useFeatureViewTracking", { enumerable: true, get: function () { return useFeatureTracking_1.useFeatureViewTracking; } });
+var useOnboardingTracking_1 = require("./hooks/useOnboardingTracking");
+Object.defineProperty(exports, "trackFlowAbandoned", { enumerable: true, get: function () { return useOnboardingTracking_1.trackFlowAbandoned; } });
+Object.defineProperty(exports, "trackFlowCompleted", { enumerable: true, get: function () { return useOnboardingTracking_1.trackFlowCompleted; } });
+Object.defineProperty(exports, "trackOnboardingAbandoned", { enumerable: true, get: function () { return useOnboardingTracking_1.trackOnboardingAbandoned; } });
+Object.defineProperty(exports, "trackOnboardingCompleted", { enumerable: true, get: function () { return useOnboardingTracking_1.trackOnboardingCompleted; } });
+Object.defineProperty(exports, "useFlowTracking", { enumerable: true, get: function () { return useOnboardingTracking_1.useFlowTracking; } });
+// Legacy exports for backward compatibility
+Object.defineProperty(exports, "useOnboardingTracking", { enumerable: true, get: function () { return useOnboardingTracking_1.useOnboardingTracking; } });
+var useScreenTracking_1 = require("./hooks/useScreenTracking");
+Object.defineProperty(exports, "useScreenTracking", { enumerable: true, get: function () { return useScreenTracking_1.useScreenTracking; } });
+var useScrollTracking_1 = require("./hooks/useScrollTracking");
+Object.defineProperty(exports, "useScrollTracking", { enumerable: true, get: function () { return useScrollTracking_1.useScrollTracking; } });
+Object.defineProperty(exports, "useWebScrollTracking", { enumerable: true, get: function () { return useScrollTracking_1.useWebScrollTracking; } });
+var reactNavigation_1 = require("./integrations/reactNavigation");
+Object.defineProperty(exports, "createNavigationTracker", { enumerable: true, get: function () { return reactNavigation_1.createNavigationTracker; } });
+Object.defineProperty(exports, "trackNavigationReady", { enumerable: true, get: function () { return reactNavigation_1.trackNavigationReady; } });
+Object.defineProperty(exports, "trackNavigationStateChange", { enumerable: true, get: function () { return reactNavigation_1.trackNavigationStateChange; } });
+// Manual screen tracking helper
+// Use this in your screens instead of automatic tracking
+function trackScreen(screenName, properties) {
+    // Add a small delay to ensure SDK is initialized
+    setTimeout(() => {
+        (0, core_1.track)("Screen Viewed", {
+            screen: screenName,
+            ...properties,
+        });
+    }, 100);
+}
+// Default export
+exports.default = exports.Axyle;

package/dist/integrations/expoRouter.d.ts

@@ -0,0 +1,42 @@
+/**
+ * Expo Router integration for automatic screen tracking
+ */
+/**
+ * Hook to track Expo Router navigation
+ * Add this to your root layout (_layout.tsx)
+ *
+ * @example
+ * ```tsx
+ * // app/_layout.tsx
+ * import { useExpoRouterTracking } from '@expo-analytics/sdk';
+ *
+ * export default function RootLayout() {
+ *   useExpoRouterTracking();
+ *
+ *   return (
+ *     <Stack>
+ *       <Stack.Screen name="index" />
+ *       <Stack.Screen name="profile" />
+ *     </Stack>
+ *   );
+ * }
+ * ```
+ */
+export declare function useExpoRouterTracking(): void;
+/**
+ * Alternative: Manual tracking for specific routes
+ *
+ * @example
+ * ```tsx
+ * import { trackExpoRoute } from '@expo-analytics/sdk';
+ *
+ * export default function ProfileScreen() {
+ *   useEffect(() => {
+ *     trackExpoRoute('Profile', { userId: '123' });
+ *   }, []);
+ *
+ *   return <View>...</View>;
+ * }
+ * ```
+ */
+export declare function trackExpoRoute(routeName: string, properties?: Record<string, any>): void;

package/dist/integrations/expoRouter.js

@@ -0,0 +1,66 @@
+"use strict";
+/**
+ * Expo Router integration for automatic screen tracking
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.useExpoRouterTracking = useExpoRouterTracking;
+exports.trackExpoRoute = trackExpoRoute;
+const react_1 = require("react");
+const expo_router_1 = require("expo-router");
+const index_1 = require("../index");
+/**
+ * Hook to track Expo Router navigation
+ * Add this to your root layout (_layout.tsx)
+ *
+ * @example
+ * ```tsx
+ * // app/_layout.tsx
+ * import { useExpoRouterTracking } from '@expo-analytics/sdk';
+ *
+ * export default function RootLayout() {
+ *   useExpoRouterTracking();
+ *
+ *   return (
+ *     <Stack>
+ *       <Stack.Screen name="index" />
+ *       <Stack.Screen name="profile" />
+ *     </Stack>
+ *   );
+ * }
+ * ```
+ */
+function useExpoRouterTracking() {
+    const pathname = (0, expo_router_1.usePathname)();
+    const segments = (0, expo_router_1.useSegments)();
+    (0, react_1.useEffect)(() => {
+        // Track screen view when pathname changes
+        if (pathname) {
+            index_1.ExpoAnalytics.track('Screen Viewed', {
+                screen: pathname,
+                segments: segments.join('/'),
+            });
+        }
+    }, [pathname, segments]);
+}
+/**
+ * Alternative: Manual tracking for specific routes
+ *
+ * @example
+ * ```tsx
+ * import { trackExpoRoute } from '@expo-analytics/sdk';
+ *
+ * export default function ProfileScreen() {
+ *   useEffect(() => {
+ *     trackExpoRoute('Profile', { userId: '123' });
+ *   }, []);
+ *
+ *   return <View>...</View>;
+ * }
+ * ```
+ */
+function trackExpoRoute(routeName, properties) {
+    index_1.ExpoAnalytics.track('Screen Viewed', {
+        screen: routeName,
+        ...properties,
+    });
+}

package/dist/integrations/reactNavigation.d.ts

@@ -0,0 +1,27 @@
+/**
+ * React Navigation integration for automatic screen tracking
+ */
+/**
+ * Create a navigation state change handler for React Navigation
+ *
+ * @example
+ * ```tsx
+ * import { NavigationContainer } from '@react-navigation/native';
+ * import { createNavigationTracker } from '@axyle/expo-sdk';
+ *
+ * const navigationTracker = createNavigationTracker();
+ *
+ * function App() {
+ *   return (
+ *     <NavigationContainer
+ *       onStateChange={navigationTracker}
+ *     >
+ *       {/* Your navigators *\/}
+ *     </NavigationContainer>
+ *   );
+ * }
+ * ```
+ */
+export declare function createNavigationTracker(): (state: any) => void;
+export declare function trackNavigationReady(navigationRef: any): void;
+export declare function trackNavigationStateChange(navigationRef: any): void;