firstusers 1.0.1 → 1.0.3

package/README.md

@@ -1,16 +1,15 @@
-# First Users SDK
+# firstusers
 
-**Automatic tester tracking with heartbeat monitoring, offline retry, device fingerprinting, and guest user auto-tracking.**
+Session tracking SDK for React Native/Expo apps. Tracks authenticated user sessions with automatic 30-second heartbeat updates.
 
 ## Features
 
-✅ **GU Auto-Tracking** — Automatically generates Guest ID and starts tracking immediately  
-🔗 **FU-GU Binding** — Links past GU activity when user enters FU ID  
-💓 **Global Heartbeat** — Persists across route changes, sends every 30 seconds  
-📶 **Offline Queue** — Failed requests queued and retried on startup  
-⏱️ **Session Duration** — Real-time tracking sent with every request  
-📱 **Device Info** — Brand (Samsung, Xiaomi…) and API level auto-detected  
-📦 **Dynamic Package Name** — Passed via props for reuse  
+✅ **Post-Login Tracking** - Only tracks authenticated user sessions (excludes login screen time)  
+✅ **Automatic Heartbeat** - Updates session duration every 30 seconds  
+✅ **Survives App Kill** - Last heartbeat data already saved (max 30s loss)  
+✅ **Zero Configuration** - Expo Config Plugin auto-configures your project  
+✅ **Privacy-Focused** - No sensitive data collection  
+✅ **Lightweight** - Minimal battery and performance impact  
 
 ## Installation
 
@@ -18,168 +17,323 @@
 npm install firstusers
 ```
 
-## Quick Start
+Or with yarn:
 
-### 1. Import the component
+```bash
+yarn add firstusers
+```
 
-```javascript
-import FirstUsersIntegration from 'firstusers';
+## Configuration
+
+### Step 1: Add Plugin to app.json
+
+```json
+{
+  "expo": {
+    "plugins": [
+      [
+        "firstusers",
+        {
+          "apiUrl": "https://your-api.workers.dev"
+        }
+      ]
+    ]
+  }
+}
 ```
 
-### 2. Add to your app
+**Plugin Options:**
 
-```jsx
-function App() {
-  return (
-    <div>
-      <h1>My App</h1>
-      
-      {/* Add First Users integration */}
-      <FirstUsersIntegration appPackageName="com.yourcompany.app" />
-      
-      {/* Your app content */}
-    </div>
-  );
-}
+| Option | Type | Required | Default |
+|--------|------|----------|---------|
+| `apiUrl` | string | No | `https://cotester-api.01hunterwl.workers.dev` |
+
+### Step 2: Rebuild Your App
+
+The Config Plugin needs a native rebuild to apply changes:
+
+```bash
+# Development build
+npx expo run:android
+
+# Or prebuild for custom builds
+npx expo prebuild --clean
 ```
 
-### 3. Track feature usage (optional)
+⚠️ **Important:** You must rebuild the app after installing this package. Expo Go does not support custom native modules.
+
+## Usage
 
-After the component is mounted, you can track specific features:
+### Basic Setup
 
-```javascript
-// Track button clicks
-window.trackFUFeature('button_click');
+```typescript
+import futracker from 'firstusers';
+import { supabase } from './lib/supabase';
 
-// Track video plays
-window.trackFUFeature('video_play');
+// Configure once at app startup
+futracker.configure('https://your-api.workers.dev');
+futracker.setPackageName('com.yourcompany.app');
 
-// Track any custom event
-window.trackFUFeature('premium_upgrade');
+// Start tracking after successful login
+supabase.auth.onAuthStateChange((event, session) => {
+  if (event === 'SIGNED_IN' && session) {
+    futracker.startTracking();
+  }
+});
 ```
 
-## How It Works
+### Alternative: Convenience Function
 
-### Automatic Guest User (GU) Tracking
+```typescript
+import { startTracking } from 'firstusers';
 
-When users first visit your app:
-1. **Auto-generates GU ID** — System creates a unique `gu-XXXXXXX` ID
-2. **Starts tracking immediately** — All activity is recorded with the GU ID
-3. **Shows yellow banner** — User sees "Anonymous Tracking Active" status
+// One-line start with package name
+if (loginSuccess) {
+  startTracking('com.yourcompany.app');
+}
+```
 
-### FU ID Binding
+### Optional: Manual Stop (usually not needed)
 
-When users enter their First Users ID:
-1. **User enters FU ID** — Format: `fu-XXXXX` (8 characters)
-2. **Binds past activity** — All previous GU data is linked to their FU account
-3. **Shows green banner** — User sees "First Users Tester Active" status
-4. **Data preserved** — Full 14-day tracking history is maintained
+```typescript
+import { stopTracking } from 'firstusers';
+
+// Optional: Call on logout
+function handleLogout() {
+  stopTracking();  // Not required - heartbeat already saved data
+  // ... rest of logout logic
+}
+```
 
 ## API Reference
 
-### Component Props
+### `futracker.configure(apiUrl: string)`
+
+Configure the API endpoint. Call once at app startup.
 
-| Prop | Type | Required | Default | Description |
-|------|------|----------|---------|-------------|
-| `appPackageName` | string | Yes | - | Your app's package name (e.g., "com.yourcompany.app") |
-| `apiEndpoint` | string | No | First Users API | Custom API endpoint if you're self-hosting |
+**Parameters:**
+- `apiUrl` (string) - Your First Users API endpoint
 
-### Global Functions
+**Example:**
+```typescript
+futracker.configure('https://your-api.workers.dev');
+```
 
-#### `window.trackFUFeature(featureName: string)`
+### `futracker.setPackageName(packageName: string)`
 
-Track custom feature usage. Available after component mounts.
+Set your app's package name (same as `applicationId` in build.gradle).
 
-```javascript
-window.trackFUFeature('search_product');
-window.trackFUFeature('checkout_completed');
+**Parameters:**
+- `packageName` (string) - Your app's package name
+
+**Example:**
+```typescript
+futracker.setPackageName('com.yourcompany.app');
 ```
 
-### Exported Utilities
+### `futracker.startTracking(packageName?: string)`
+
+Start tracking user session. Call after successful login.
 
-#### `FUHeartbeat`
+**Parameters:**
+- `packageName` (string, optional) - Override package name for this call
 
-Global heartbeat manager singleton.
+**Example:**
+```typescript
+// Use pre-configured package name
+futracker.startTracking();
 
-```javascript
-import { FUHeartbeat } from 'firstusers';
+// Or pass directly
+futracker.startTracking('com.yourcompany.app');
+```
 
-// Start heartbeat manually (usually handled by component)
-FUHeartbeat.start('fu-12345', trackFunction);
+### `futracker.stopTracking()`
 
-// Get current session duration in seconds
-const duration = FUHeartbeat.getDuration();
+Stop tracking session. **Optional** - heartbeat auto-saves data every 30s.
 
-// Stop heartbeat
-FUHeartbeat.stop();
+**Example:**
+```typescript
+futracker.stopTracking();
 ```
 
-#### `generateGuestId()`
+### `futracker.setDebug(enabled: boolean)`
 
-Generate a unique Guest User ID.
+Enable or disable debug logging. Debug mode is enabled by default.
 
-```javascript
-import { generateGuestId } from 'firstusers';
+**Parameters:**
+- `enabled` (boolean) - Whether to enable debug logs
 
-const guestId = generateGuestId(); // Returns: "gu-abc123xyz"
+**Example:**
+```typescript
+// Disable debug logs in production
+futracker.setDebug(false);
 ```
 
-#### `getOrCreateUserId()`
+### `futracker.isActive()`
 
-Get existing user ID from localStorage or create new GU ID.
+Check if tracking is currently active.
+
+**Returns:** boolean indicating if tracking is active
+
+**Example:**
+```typescript
+if (futracker.isActive()) {
+  console.log('Tracking is running');
+}
+```
 
-```javascript
-import { getOrCreateUserId } from 'firstusers';
+## How It Works
 
-const userId = getOrCreateUserId(); // Returns: "fu-12345" or "gu-abc123"
+1. **Initial Record**: When `startTracking()` is called, creates one record in `fu_tracking` table with `session_duration = 0`
+2. **Heartbeat Updates**: Every 30 seconds, UPDATE the same record's `session_duration` to current elapsed time
+3. **App Kill Safety**: If app is killed, last heartbeat data is already saved (accurate within ~30 seconds)
+4. **No Data Loss**: No need to call `stopTracking()` - heartbeat already persisted the duration
+
+## Database Schema
+
+The tracker sends data to the `fu_tracking` table:
+
+```sql
+CREATE TABLE fu_tracking (
+  id INTEGER PRIMARY KEY AUTOINCREMENT,
+  fu_id TEXT NOT NULL,              -- Guest ID (gu-XXXXX) or User ID (fu-XXXXX)
+  app_package TEXT NOT NULL,         -- Your app's package name
+  timestamp TEXT NOT NULL,           -- ISO 8601 UTC timestamp
+  action TEXT NOT NULL,              -- 'session_start'
+  device_brand TEXT,                 -- Device manufacturer
+  device_api_level TEXT,             -- Android version
+  user_agent TEXT,                   -- Platform info
+  session_id TEXT NOT NULL,          -- Unique session identifier
+  session_duration INTEGER NOT NULL  -- Seconds since session start
+);
 ```
 
-#### `getDeviceInfo()`
+## Data Collected
+
+**Session Data:**
+- Session start time (UTC timestamp)
+- Session duration (seconds)
+- Session ID (unique per app open)
+
+**Device Info:**
+- Device manufacturer (e.g., "Google", "Samsung")
+- Android API level (e.g., "Android 33")
+- Platform (e.g., "Android/13")
 
-Extract device information from user agent.
+**No Personal Data:**
+- ❌ No user location
+- ❌ No contact information
+- ❌ No sensitive permissions
 
-```javascript
-import { getDeviceInfo } from 'firstusers';
+## Troubleshooting
 
-const device = getDeviceInfo();
-// Returns: {
-//   device_brand: "Samsung",
-//   device_api_level: "Android 13",
-//   user_agent: "Mozilla/5.0..."
-// }
+### Module not found error
+
+**Error:** `The package 'firstusers' doesn't seem to be linked`
+
+**Solution:** You must rebuild the native app:
+```bash
+npx expo run:android
 ```
 
-## UI States
+### Tracking not starting
 
-### 1. Initial State (Rare)
-Gray banner asking user to enter FU ID (only shown if GU auto-generation fails).
+**Check:**
+1. Did you call `setPackageName()` before `startTracking()`?
+2. Is the package name correct? (Check `android/app/build.gradle` → `applicationId`)
+3. Did you rebuild after installing the package?
 
-### 2. Anonymous Tracking (GU Active)
-Yellow banner showing:
-- Current Guest ID
-- Session duration
-- Input field to enter FU ID
-- "Link FU ID" button
+**Debug:**
+```typescript
+// Enable console logs
+futracker.configure('https://your-api.workers.dev');
+futracker.setPackageName('com.yourcompany.app');
+futracker.startTracking();
+// Check console for "[FirstUsers]" logs
+```
+
+### Build errors
 
-### 3. Active Tracking (FU Active)
-Green banner showing:
-- FU ID is active
-- Session duration
+**Error:** `Plugin [id: 'expo-module-gradle-plugin'] was not found`
 
-## Data Privacy
+**Solution:** Clean and rebuild:
+```bash
+cd android
+./gradlew clean
+cd ..
+npx expo prebuild --clean
+npx expo run:android
+```
 
-- All data is stored in First Users' secure database
-- User IDs are anonymized (GU or FU format)
-- Device info helps identify unique testers
-- Session data used for 14-day activity tracking
+## Requirements
+
+- **React Native:** 0.70+
+- **Expo:** 50+
+- **Android:** API 24+ (Android 7.0)
+- **Kotlin:** 1.8+
+
+## Example Integration
+
+Complete example with Supabase authentication:
+
+```typescript
+// App.tsx
+import React, { useEffect } from 'react';
+import futracker from 'firstusers';
+import { supabase } from './lib/supabase';
+
+export default function App() {
+  useEffect(() => {
+    // Configure tracker once
+    futracker.configure('https://cotester-api.01hunterwl.workers.dev');
+    futracker.setPackageName('net.woodlogos.app.firstusers');
+
+    // Listen for auth changes
+    const { data: authListener } = supabase.auth.onAuthStateChange(
+      async (event, session) => {
+        if (event === 'SIGNED_IN' && session) {
+          // Start tracking after successful login
+          futracker.startTracking();
+          console.log('✅ Tracking started for authenticated user');
+        }
+      }
+    );
+
+    return () => {
+      authListener?.subscription.unsubscribe();
+    };
+  }, []);
 
-## Support
+  return (
+    // Your app components
+  );
+}
+```
+
+## Privacy & Compliance
 
-For issues or questions:
-- Email: support@firstusers.com
-- Documentation: https://docs.firstusers.com
-- GitHub: https://github.com/firstusers/firstusers-sdk
+**GDPR Compliant:** Only tracks usage duration and basic device info (no personal data)
+
+**Disclose in Privacy Policy:**
+```
+This app collects anonymous usage data for beta testing:
+- Session duration (start/end time)
+- Device model and Android version
+- App package name
+
+No personal information is collected.
+```
 
 ## License
 
 MIT
+
+## Support
+
+- **Issues:** [GitHub Issues](https://github.com/firstusers/react-native-tracker/issues)
+- **Documentation:** [GitHub Wiki](https://github.com/firstusers/react-native-tracker/wiki)
+- **Email:** support@firstusers.io
+
+---
+
+**Made with ❤️ by First Users Team**

package/android/build.gradle

@@ -0,0 +1,32 @@
+apply plugin: 'com.android.library'
+apply plugin: 'kotlin-android'
+apply plugin: 'expo-module-gradle-plugin'
+
+android {
+    namespace "com.firstusers.tracker"
+    compileSdkVersion safeExtGet("compileSdkVersion", 34)
+
+    defaultConfig {
+        minSdkVersion safeExtGet("minSdkVersion", 24)
+        targetSdkVersion safeExtGet("targetSdkVersion", 34)
+    }
+
+    compileOptions {
+        sourceCompatibility JavaVersion.VERSION_17
+        targetCompatibility JavaVersion.VERSION_17
+    }
+
+    kotlinOptions {
+        jvmTarget = "17"
+    }
+}
+
+dependencies {
+    implementation "org.jetbrains.kotlin:kotlin-stdlib-jdk8"
+    implementation "org.jetbrains.kotlinx:kotlinx-coroutines-android:1.7.3"
+    implementation "org.jetbrains.kotlinx:kotlinx-coroutines-core:1.7.3"
+}
+
+def safeExtGet(prop, fallback) {
+    rootProject.ext.has(prop) ? rootProject.ext.get(prop) : fallback
+}

package/android/src/main/java/com/firstusers/tracker/FirstUsers.kt

@@ -0,0 +1,113 @@
+package com.firstusers.tracker
+
+import android.content.Context
+import android.os.Build
+import kotlinx.coroutines.*
+import org.json.JSONObject
+import java.net.HttpURLConnection
+import java.net.URL
+import java.text.SimpleDateFormat
+import java.util.*
+
+object FirstUsers {
+    private const val P = "fu_prefs"
+    private const val K = "fu_device_id"
+    private var apiUrl = "https://cotester-api.01hunterwl.workers.dev"
+    private var sid = ""
+    private var t0 = 0L
+    private var pkg = ""
+    private var tmr: Timer? = null
+    private var isTracking = false
+
+    fun configure(url: String) {
+        apiUrl = url
+    }
+
+    fun start(c: Context, ap: String) {
+        // Prevent duplicate tracking sessions
+        if (isTracking) {
+            android.util.Log.d("FirstUsers", "Already tracking, ignoring duplicate start call")
+            return
+        }
+        isTracking = true
+        
+        // Cancel previous timer if exists (prevent duplicate timers)
+        tmr?.cancel()
+        tmr = null
+        
+        pkg = ap
+        sid = "s_" + UUID.randomUUID().toString().take(8)
+        t0 = System.currentTimeMillis()
+        
+        // Create initial record (session_duration = 0)
+        post("$apiUrl/api/fu/track",
+            JSONObject()
+            .put("fu_id", gid(c))
+            .put("app_package", pkg)
+            .put("timestamp", ts())
+            .put("action","session_start")
+            .put("device_brand", Build.MANUFACTURER)
+            .put("device_api_level", "Android "+Build.VERSION.SDK_INT)
+            .put("user_agent", "Android/"+Build.VERSION.RELEASE)
+            .put("session_id", sid)
+            .put("session_duration", 0))
+        
+        // Heartbeat every 30s to update session_duration
+        tmr = Timer()
+        tmr?.schedule(object:TimerTask(){
+            override fun run() { hb() }
+        }, 30000, 30000)
+    }
+
+    fun stop(c: Context) {
+        if (!isTracking) return
+        isTracking = false
+        tmr?.cancel()
+        tmr = null
+        hb() // final update
+    }
+
+    private fun dur() = ((System.currentTimeMillis()-t0)/1000).toInt()
+
+    private fun hb() {
+        post("$apiUrl/api/fu/track/heartbeat",
+            JSONObject()
+            .put("session_id", sid)
+            .put("session_duration",dur()))
+    }
+
+    private fun ts(): String {
+        val f = SimpleDateFormat("yyyy-MM-dd'T'HH:mm:ss", Locale.US)
+        f.timeZone = TimeZone.getTimeZone("UTC")
+        return f.format(Date())
+    }
+
+    private fun gid(c: Context): String {
+        val sp = c.getSharedPreferences(P, Context.MODE_PRIVATE)
+        var id = sp.getString(K, null)
+        if (id == null) {
+            id = "gu-" + UUID.randomUUID().toString().take(5)
+            sp.edit().putString(K, id).apply()
+        }
+        return id
+    }
+
+    private fun post(u: String, j: JSONObject) {
+        CoroutineScope(Dispatchers.IO).launch {
+            try {
+                val c = URL(u).openConnection() as HttpURLConnection
+                c.requestMethod = "POST"
+                c.setRequestProperty("Content-Type", "application/json")
+                c.doOutput = true
+                c.connectTimeout = 5000
+                c.outputStream.use {
+                    it.write(j.toString().toByteArray())
+                }
+                c.responseCode
+                c.disconnect()
+            } catch (e: Exception) {
+                android.util.Log.w("FirstUsers", "Network request failed: ${e.message}")
+            }
+        }
+    }
+}

package/android/src/main/java/com/firstusers/tracker/FirstUsersModule.kt

@@ -0,0 +1,29 @@
+package com.firstusers.tracker
+
+import android.content.Context
+import expo.modules.kotlin.modules.Module
+import expo.modules.kotlin.modules.ModuleDefinition
+
+class FirstUsersModule : Module() {
+  override fun definition() = ModuleDefinition {
+    Name("FirstUsersTracker")
+
+    Function("configure") { apiUrl: String ->
+      FirstUsers.configure(apiUrl)
+    }
+
+    Function("start") { packageName: String ->
+      val context = appContext.reactContext as? Context
+      context?.let {
+        FirstUsers.start(it, packageName)
+      }
+    }
+
+    Function("stop") {
+      val context = appContext.reactContext as? Context
+      context?.let {
+        FirstUsers.stop(it)
+      }
+    }
+  }
+}

package/build/index.d.ts

@@ -0,0 +1,48 @@
+export declare class futracker {
+    private static apiUrl;
+    private static packageName;
+    private static isTracking;
+    private static debugMode;
+    /**
+     * Configure the tracker with custom API URL
+     * @param apiUrl - Your First Users API endpoint
+     */
+    static configure(apiUrl: string): void;
+    /**
+     * Enable or disable debug logging
+     * @param enabled - Whether to enable debug logs
+     */
+    static setDebug(enabled: boolean): void;
+    /**
+     * Set the package name (usually from build.gradle applicationId)
+     * @param packageName - Your app's package name
+     */
+    static setPackageName(packageName: string): void;
+    /**
+     * Start tracking user session
+     * Call this after successful user login
+     * @param packageName - Optional: override package name
+     */
+    static startTracking(packageName?: string): void;
+    /**
+     * Stop tracking user session
+     * Optional: Can be called on logout, but heartbeat already auto-saves every 30s
+     */
+    static stopTracking(): void;
+    /**
+     * Check if tracking is currently active
+     * @returns boolean indicating if tracking is active
+     */
+    static isActive(): boolean;
+}
+/**
+ * Convenience function for quick start
+ * @param packageName - Your app's package name
+ * @param apiUrl - Optional: custom API URL
+ */
+export declare function startTracking(packageName: string, apiUrl?: string): void;
+/**
+ * Convenience function for stop
+ */
+export declare function stopTracking(): void;
+export default futracker;

package/build/index.js

@@ -0,0 +1,119 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.futracker = void 0;
+exports.startTracking = startTracking;
+exports.stopTracking = stopTracking;
+const react_native_1 = require("react-native");
+const LINKING_ERROR = `The package 'firstusers' doesn't seem to be linked. Make sure:\n\n` +
+    react_native_1.Platform.select({ ios: "- Run 'pod install'\n", default: '' }) +
+    '- You rebuilt the app after installing the package\n' +
+    '- You are not using Expo Go (this module requires custom native code)\n';
+const FirstUsersTrackerModule = react_native_1.NativeModules.FirstUsersTracker
+    ? react_native_1.NativeModules.FirstUsersTracker
+    : new Proxy({}, {
+        get() {
+            throw new Error(LINKING_ERROR);
+        },
+    });
+class futracker {
+    /**
+     * Configure the tracker with custom API URL
+     * @param apiUrl - Your First Users API endpoint
+     */
+    static configure(apiUrl) {
+        this.apiUrl = apiUrl;
+        FirstUsersTrackerModule.configure(apiUrl);
+        if (this.debugMode)
+            console.log('[FirstUsers] Configured with API:', apiUrl);
+    }
+    /**
+     * Enable or disable debug logging
+     * @param enabled - Whether to enable debug logs
+     */
+    static setDebug(enabled) {
+        this.debugMode = enabled;
+    }
+    /**
+     * Set the package name (usually from build.gradle applicationId)
+     * @param packageName - Your app's package name
+     */
+    static setPackageName(packageName) {
+        this.packageName = packageName;
+    }
+    /**
+     * Start tracking user session
+     * Call this after successful user login
+     * @param packageName - Optional: override package name
+     */
+    static startTracking(packageName) {
+        const pkg = packageName || this.packageName;
+        if (!pkg) {
+            console.error('[FirstUsers] Package name not set. Call setPackageName() or pass it as argument.');
+            return;
+        }
+        if (this.isTracking) {
+            if (this.debugMode)
+                console.log('[FirstUsers] Already tracking, ignoring duplicate call');
+            return;
+        }
+        try {
+            FirstUsersTrackerModule.start(pkg);
+            this.isTracking = true;
+            if (this.debugMode)
+                console.log('[FirstUsers] Tracking started for:', pkg);
+        }
+        catch (error) {
+            console.error('[FirstUsers] Failed to start tracking:', error);
+        }
+    }
+    /**
+     * Stop tracking user session
+     * Optional: Can be called on logout, but heartbeat already auto-saves every 30s
+     */
+    static stopTracking() {
+        if (!this.isTracking) {
+            if (this.debugMode)
+                console.log('[FirstUsers] Not currently tracking');
+            return;
+        }
+        try {
+            FirstUsersTrackerModule.stop();
+            this.isTracking = false;
+            if (this.debugMode)
+                console.log('[FirstUsers] Tracking stopped');
+        }
+        catch (error) {
+            console.error('[FirstUsers] Failed to stop tracking:', error);
+        }
+    }
+    /**
+     * Check if tracking is currently active
+     * @returns boolean indicating if tracking is active
+     */
+    static isActive() {
+        return this.isTracking;
+    }
+}
+exports.futracker = futracker;
+futracker.apiUrl = 'https://cotester-api.01hunterwl.workers.dev';
+futracker.packageName = '';
+futracker.isTracking = false;
+futracker.debugMode = true;
+/**
+ * Convenience function for quick start
+ * @param packageName - Your app's package name
+ * @param apiUrl - Optional: custom API URL
+ */
+function startTracking(packageName, apiUrl) {
+    if (apiUrl) {
+        futracker.configure(apiUrl);
+    }
+    futracker.startTracking(packageName);
+}
+/**
+ * Convenience function for stop
+ */
+function stopTracking() {
+    futracker.stopTracking();
+}
+exports.default = futracker;

package/expo-module.config.json

@@ -0,0 +1,6 @@
+{
+  "platforms": ["android"],
+  "android": {
+    "modules": ["com.firstusers.tracker.FirstUsersModule"]
+  }
+}

package/package.json

@@ -1,42 +1,47 @@
 {
   "name": "firstusers",
-  "version": "1.0.1",
-  "description": "First Users - Automatic tester tracking with heartbeat monitoring, offline retry, device fingerprinting, and guest user auto-tracking",
-  "main": "dist/index.js",
-  "types": "index.d.ts",
-  "files": [
-    "dist",
-    "index.d.ts",
-    "README.md",
-    "LICENSE"
-  ],
+  "version": "1.0.3",
+  "description": "Usage tracking SDK for React Native/Expo apps. Tracks authenticated user sessions with 30s heartbeat to First Users platform.",
+  "main": "build/index.js",
+  "types": "build/index.d.ts",
+  "app.plugin": "./plugin/src/withFirstUsers.js",
   "scripts": {
-    "test": "echo \"Error: no test specified\" && exit 1",
-    "prepublishOnly": "echo 'Publishing firstusers package...' && ls -la dist/"
+    "build": "tsc",
+    "prepare": "npm run build"
   },
   "keywords": [
-    "firstusers",
-    "tracking",
+    "react-native",
+    "expo",
     "analytics",
-    "tester",
-    "heartbeat",
-    "offline",
-    "react",
-    "guest-user"
+    "tracking",
+    "session",
+    "beta-testing",
+    "first-users"
   ],
   "author": "First Users Team",
   "license": "MIT",
+  "peerDependencies": {
+    "expo": ">=50.0.0",
+    "react": "*",
+    "react-native": "*"
+  },
+  "devDependencies": {
+    "@expo/config-plugins": "^9.0.0",
+    "@types/react": "^19.0.0",
+    "typescript": "^5.3.0"
+  },
   "repository": {
     "type": "git",
-    "url": "https://github.com/01hunterwl-commits/fucallback.git"
-  },
-  "peerDependencies": {
-    "react": ">=16.8.0"
+    "url": "https://github.com/firstusers/react-native-tracker.git"
   },
-  "engines": {
-    "node": ">=14.0.0"
+  "bugs": {
+    "url": "https://github.com/firstusers/react-native-tracker/issues"
   },
-  "devDependencies": {
-    "npm-packlist": "^10.0.3"
-  }
+  "homepage": "https://github.com/firstusers/react-native-tracker#readme",
+  "files": [
+    "build/",
+    "android/",
+    "plugin/",
+    "expo-module.config.json"
+  ]
 }

package/plugin/src/withFirstUsers.js

@@ -0,0 +1,60 @@
+const { withAndroidManifest, withAppBuildGradle } = require('@expo/config-plugins');
+
+/**
+ * Expo Config Plugin for First Users Tracker
+ * Automatically configures Android project for session tracking
+ */
+function withFirstUsers(config, props = {}) {
+  const apiUrl = props.apiUrl || 'https://cotester-api.01hunterwl.workers.dev';
+
+  // Add INTERNET and DETECT_SCREEN_CAPTURE permissions to AndroidManifest.xml
+  config = withAndroidManifest(config, (config) => {
+    const androidManifest = config.modResults;
+    const mainApplication = androidManifest.manifest;
+
+    // Ensure permissions array exists
+    if (!mainApplication['uses-permission']) {
+      mainApplication['uses-permission'] = [];
+    }
+
+    const permissions = mainApplication['uses-permission'];
+
+    // Add INTERNET permission if not exists
+    const hasInternet = permissions.some(
+      (perm) => perm.$?.['android:name'] === 'android.permission.INTERNET'
+    );
+    if (!hasInternet) {
+      permissions.push({
+        $: { 'android:name': 'android.permission.INTERNET' }
+      });
+    }
+
+    return config;
+  });
+
+  // Add Kotlin Coroutines dependencies to app/build.gradle
+  config = withAppBuildGradle(config, (config) => {
+    const buildGradle = config.modResults.contents;
+
+    // Check if coroutines dependencies already exist
+    if (!buildGradle.includes('kotlinx-coroutines-android')) {
+      // Add dependencies after the dependencies block starts
+      const dependenciesRegex = /dependencies\s*{/;
+      if (dependenciesRegex.test(buildGradle)) {
+        config.modResults.contents = buildGradle.replace(
+          dependenciesRegex,
+          `dependencies {
+    // First Users Tracker - Kotlin Coroutines
+    implementation 'org.jetbrains.kotlinx:kotlinx-coroutines-android:1.7.3'
+    implementation 'org.jetbrains.kotlinx:kotlinx-coroutines-core:1.7.3'`
+        );
+      }
+    }
+
+    return config;
+  });
+
+  return config;
+}
+
+module.exports = withFirstUsers;

package/LICENSE

@@ -1,21 +0,0 @@
-MIT License
-
-Copyright (c) 2026 First Users Team
-
-Permission is hereby granted, free of charge, to any person obtaining a copy
-of this software and associated documentation files (the "Software"), to deal
-in the Software without restriction, including without limitation the rights
-to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
-copies of the Software, and to permit persons to whom the Software is
-furnished to do so, subject to the following conditions:
-
-The above copyright notice and this permission notice shall be included in all
-copies or substantial portions of the Software.
-
-THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
-IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
-FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
-AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
-LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
-OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
-SOFTWARE.

package/dist/index.js

@@ -1,304 +0,0 @@
-import React, { useState, useEffect, useRef } from 'react';
-
-// ---- Global Heartbeat Manager (persists across route changes) ----
-const FUHeartbeat = {
-  _interval: null,
-  _startTime: null,
-  _fuId: null,
-  _trackFn: null,
-  start(fuId, trackFn) {
-    if (this._interval) return; // already running
-    this._fuId = fuId;
-    this._trackFn = trackFn;
-    this._startTime = Date.now();
-    this._interval = setInterval(() => {
-      const dur = Math.floor((Date.now() - this._startTime) / 1000);
-      this._trackFn(this._fuId, 'heartbeat', { session_duration: dur });
-    }, 30000);
-    if (typeof window !== 'undefined') {
-      window.addEventListener('beforeunload', this._onUnload);
-    }
-  },
-  _onUnload() {
-    FUHeartbeat.stop(true);
-  },
-  stop(sendEnd = false) {
-    if (!this._interval) return;
-    clearInterval(this._interval);
-    if (sendEnd && this._trackFn && this._fuId) {
-      const dur = Math.floor((Date.now() - this._startTime) / 1000);
-      this._trackFn(this._fuId, 'session_end', { session_duration: dur });
-    }
-    if (typeof window !== 'undefined') {
-      window.removeEventListener('beforeunload', this._onUnload);
-    }
-    this._interval = null;
-  },
-  getDuration() {
-    if (!this._startTime) return 0;
-    return Math.floor((Date.now() - this._startTime) / 1000);
-  }
-};
-
-// ---- GU (Guest User) Auto-Generation ----
-function generateGuestId() {
-  const randomStr = Math.random().toString(36).substr(2, 9);
-  return 'gu-' + randomStr;
-}
-
-function getOrCreateUserId() {
-  if (typeof localStorage === 'undefined') return null;
-  let userId = localStorage.getItem('fu_tester_id');
-  if (!userId) {
-    // Auto-generate GU ID for anonymous tracking
-    userId = generateGuestId();
-    localStorage.setItem('fu_tester_id', userId);
-    console.log('Auto-generated Guest User ID:', userId);
-  }
-  return userId;
-}
-
-// ---- Device Info Helper ----
-function getDeviceInfo() {
-  const ua = (typeof navigator !== 'undefined' ? navigator.userAgent : '') || '';
-  let device_brand = 'unknown';
-  let device_api_level = 'unknown';
-  // Detect brand from common UA patterns
-  const brands = ['Samsung','Xiaomi','Huawei','OnePlus','Oppo','Vivo','Realme',
-    'Motorola','LG','Sony','Google','Pixel','Nokia','Asus','ZTE','Lenovo'];
-  for (const b of brands) {
-    if (ua.toLowerCase().includes(b.toLowerCase())) { device_brand = b; break; }
-  }
-  // Detect Android API level
-  const androidMatch = ua.match(/Android\s([\d.]+)/);
-  if (androidMatch) device_api_level = 'Android ' + androidMatch[1];
-  const iosMatch = ua.match(/OS\s([\d_]+)\slike/);
-  if (iosMatch) device_api_level = 'iOS ' + iosMatch[1].replace(/_/g, '.');
-  return { device_brand, device_api_level, user_agent: ua };
-}
-
-// ---- Offline Queue ----
-function queueFailedRequest(data) {
-  if (typeof localStorage === 'undefined') return;
-  try {
-    const q = JSON.parse(localStorage.getItem('fu_failed_requests') || '[]');
-    q.push({ ...data, queued_at: new Date().toISOString() });
-    localStorage.setItem('fu_failed_requests', JSON.stringify(q));
-  } catch (e) { console.error('Queue error:', e); }
-}
-
-async function processFailedRequests(trackFn) {
-  if (typeof localStorage === 'undefined') return;
-  try {
-    const q = JSON.parse(localStorage.getItem('fu_failed_requests') || '[]');
-    if (!q.length) return;
-    const remaining = [];
-    for (const req of q) {
-      const ok = await trackFn(req.fu_id, req.action, req, false);
-      if (!ok) remaining.push(req);
-    }
-    localStorage.setItem('fu_failed_requests', JSON.stringify(remaining));
-  } catch (e) { console.error('Retry error:', e); }
-}
-
-/**
- * First Users Integration Component
- * @param {Object} props
- * @param {string} props.appPackageName - Your app's package name (e.g., "com.yourcompany.app")
- * @param {string} [props.apiEndpoint] - Custom API endpoint (default: First Users API)
- */
-function FirstUsersIntegration({ appPackageName = 'your.package.name', apiEndpoint = 'https://cotester-api.01hunterwl.workers.dev' }) {
-  const [fuId, setFuId] = useState('');
-  const [isSubmitting, setIsSubmitting] = useState(false);
-  const [isTracked, setIsTracked] = useState(false);
-  const [sessionDuration, setSessionDuration] = useState(0);
-  const timerRef = useRef(null);
-  const sessionId = React.useMemo(() =>
-    'session_' + Math.random().toString(36).substr(2, 9), []
-  );
-
-  const trackActivity = async (fuIdToTrack, action = 'app_usage', extraData = {}, shouldQueue = true) => {
-    try {
-      const device = getDeviceInfo();
-      const requestData = {
-        fu_id: fuIdToTrack,
-        app_package: appPackageName,
-        timestamp: new Date().toISOString(),
-        action,
-        page_url: typeof window !== 'undefined' ? (window.location?.pathname + window.location?.search) : '',
-        user_agent: device.user_agent,
-        device_brand: device.device_brand,
-        device_api_level: device.device_api_level,
-        session_id: sessionId,
-        session_duration: FUHeartbeat.getDuration(),
-        ...extraData
-      };
-      const resp = await fetch(`${apiEndpoint}/api/fu/track`, {
-        method: 'POST',
-        headers: { 'Content-Type': 'application/json' },
-        body: JSON.stringify(requestData),
-      });
-      const result = await resp.json();
-      if (result.success) { console.log('FU tracked:', result); return true; }
-      if (shouldQueue) queueFailedRequest(requestData);
-      return false;
-    } catch (e) {
-      console.error('FU error:', e);
-      if (shouldQueue) queueFailedRequest({ fu_id: fuIdToTrack, app_package: appPackageName, action, ...extraData });
-      return false;
-    }
-  };
-
-  // On mount: restore tracked state, process offline queue, start heartbeat
-  useEffect(() => {
-    const userId = getOrCreateUserId(); // Auto-generate GU if needed
-    if (!userId) return; // Skip if localStorage unavailable
-    
-    setFuId(userId);
-    
-    // Determine if this is a real FU or auto-generated GU
-    const isRealFU = userId.startsWith('fu-');
-    setIsTracked(isRealFU);
-    
-    // Start tracking immediately with either FU or GU
-    trackActivity(userId, 'page_visit');
-    FUHeartbeat.start(userId, trackActivity);
-    
-    // Process any queued offline requests on startup
-    processFailedRequests(trackActivity);
-    // Update duration display every second
-    timerRef.current = setInterval(() => setSessionDuration(FUHeartbeat.getDuration()), 1000);
-    return () => { 
-      if (timerRef.current) clearInterval(timerRef.current); 
-    };
-  }, []);
-
-  // Bind GU to FU when user submits their FU ID
-  const bindGuestToFU = async (guId, fuId) => {
-    try {
-      const resp = await fetch(`${apiEndpoint}/api/fu/bind`, {
-        method: 'POST',
-        headers: { 'Content-Type': 'application/json' },
-        body: JSON.stringify({ gu_id: guId, fu_id: fuId }),
-      });
-      const result = await resp.json();
-      return result.success;
-    } catch (e) {
-      console.error('Bind error:', e);
-      return false;
-    }
-  };
-
-  const handleSubmitFuId = async () => {
-    if (!fuId.startsWith('fu-') || fuId.length !== 8) {
-      alert('Please enter a valid FU ID (format: fu-XXXXX)');
-      return;
-    }
-    setIsSubmitting(true);
-    
-    // Get current ID (might be GU)
-    const currentId = typeof localStorage !== 'undefined' ? localStorage.getItem('fu_tester_id') : null;
-    const isGU = currentId && currentId.startsWith('gu-');
-    
-    // If upgrading from GU to FU, bind them first
-    if (isGU) {
-      const bindSuccess = await bindGuestToFU(currentId, fuId);
-      if (!bindSuccess) {
-        alert('Failed to link your previous activity. Please try again.');
-        setIsSubmitting(false);
-        return;
-      }
-      console.log(`Successfully bound ${currentId} to ${fuId}`);
-    }
-    
-    // Register the FU ID
-    const ok = await trackActivity(fuId, 'tester_registration');
-    if (ok) {
-      alert('Your testing activity is now being tracked with your FU ID.');
-      if (typeof localStorage !== 'undefined') {
-        localStorage.setItem('fu_tester_id', fuId);
-      }
-      setIsTracked(true);
-      // Restart heartbeat with new FU ID
-      FUHeartbeat.stop();
-      FUHeartbeat.start(fuId, trackActivity);
-    } else {
-      alert('Failed to register. Will retry automatically.');
-    }
-    setIsSubmitting(false);
-  };
-
-  // Expose global feature tracker
-  useEffect(() => {
-    if (typeof window !== 'undefined') {
-      window.trackFUFeature = (name) => {
-        const id = localStorage.getItem('fu_tester_id');
-        if (id) trackActivity(id, `feature_${name}`);
-      };
-    }
-  }, []);
-
-  const currentId = typeof localStorage !== 'undefined' ? localStorage.getItem('fu_tester_id') : '';
-  const isGU = currentId && currentId.startsWith('gu-');
-
-  if (isTracked) {
-    return (
-      <div style={{ padding:'15px', backgroundColor:'#dcfce7', borderRadius:'8px',
-        margin:'20px 0', border:'1px solid #bbf7d0' }}>
-        <h4 style={{ color:'#16a34a', margin:'0 0 5px' }}>First Users Tester Active</h4>
-        <p style={{ margin:0, fontSize:'14px', color:'#15803d' }}>
-          Tracking active with FU ID. Session: {Math.floor(sessionDuration/60)}m {sessionDuration%60}s
-        </p>
-      </div>
-    );
-  }
-
-  if (isGU) {
-    return (
-      <div style={{ padding:'20px', backgroundColor:'#fff3cd', borderRadius:'8px',
-        margin:'20px 0', border:'1px solid #ffc107' }}>
-        <h3 style={{ color:'#856404', marginTop:0 }}>Anonymous Tracking Active</h3>
-        <p style={{ fontSize:'14px', color:'#856404', margin:'10px 0' }}>
-          Currently tracking with Guest ID: <code>{currentId}</code>
-        </p>
-        <p style={{ fontSize:'14px', color:'#856404', margin:'10px 0' }}>
-          Session: {Math.floor(sessionDuration/60)}m {sessionDuration%60}s
-        </p>
-        <p style={{ fontSize:'14px', color:'#856404', fontWeight:'bold', margin:'10px 0' }}>
-          Enter your FU ID to link your activity:
-        </p>
-        <input type="text" placeholder="fu-12345" value={fuId}
-          onChange={(e) => setFuId(e.target.value)}
-          style={{ padding:'10px', marginRight:'10px', border:'1px solid #ddd',
-            borderRadius:'4px', minWidth:'120px' }} />
-        <button onClick={handleSubmitFuId} disabled={isSubmitting}
-          style={{ padding:'10px 20px', backgroundColor: isSubmitting?'#9ca3af':'#3b82f6',
-            color:'white', border:'none', borderRadius:'4px',
-            cursor: isSubmitting?'not-allowed':'pointer' }}>
-          {isSubmitting ? 'Linking...' : 'Link FU ID'}
-        </button>
-      </div>
-    );
-  }
-
-  return (
-    <div style={{ padding:'20px', backgroundColor:'#f5f5f5', borderRadius:'8px',
-      margin:'20px 0', border:'1px solid #d1d5db' }}>
-      <h3>First Users Tester</h3>
-      <p>Enter your FU ID to start tracking:</p>
-      <input type="text" placeholder="fu-12345" value={fuId}
-        onChange={(e) => setFuId(e.target.value)}
-        style={{ padding:'10px', marginRight:'10px', border:'1px solid #ddd',
-          borderRadius:'4px', minWidth:'120px' }} />
-      <button onClick={handleSubmitFuId} disabled={isSubmitting}
-        style={{ padding:'10px 20px', backgroundColor: isSubmitting?'#9ca3af':'#3b82f6',
-          color:'white', border:'none', borderRadius:'4px',
-          cursor: isSubmitting?'not-allowed':'pointer' }}>
-        {isSubmitting ? 'Registering...' : 'Start Tracking'}
-      </button>
-    </div>
-  );
-}
-
-export default FirstUsersIntegration;
-export { FUHeartbeat, generateGuestId, getOrCreateUserId, getDeviceInfo };

package/index.d.ts

@@ -1,59 +0,0 @@
-import React from 'react';
-
-export interface FirstUsersIntegrationProps {
-  /**
-   * Your application's package name (e.g., "com.yourcompany.app")
-   */
-  appPackageName: string;
-  
-  /**
-   * Custom API endpoint (optional, defaults to First Users API)
-   */
-  apiEndpoint?: string;
-}
-
-/**
- * First Users Integration Component
- * Provides automatic tester tracking with heartbeat monitoring, offline retry,
- * device fingerprinting, and guest user auto-tracking.
- */
-declare const FirstUsersIntegration: React.FC<FirstUsersIntegrationProps>;
-
-export default FirstUsersIntegration;
-
-/**
- * Global heartbeat manager singleton
- */
-export const FUHeartbeat: {
-  start(fuId: string, trackFn: (id: string, action: string, data?: any) => Promise<boolean>): void;
-  stop(sendEnd?: boolean): void;
-  getDuration(): number;
-};
-
-/**
- * Generate a unique Guest User ID
- */
-export function generateGuestId(): string;
-
-/**
- * Get existing user ID or create new Guest User ID
- */
-export function getOrCreateUserId(): string | null;
-
-/**
- * Extract device information from user agent
- */
-export function getDeviceInfo(): {
-  device_brand: string;
-  device_api_level: string;
-  user_agent: string;
-};
-
-/**
- * Global feature tracking function (available after component mount)
- */
-declare global {
-  interface Window {
-    trackFUFeature?: (featureName: string) => void;
-  }
-}