react-native-edgee 1.0.7 → 1.0.9

package/README.md

@@ -1,20 +1,13 @@
-# react-native-edgee
+# Edgee data collection sdk for React Native 
 
-Lightweight Edgee data collection client for React Native with comprehensive native context collection.
+For React Native applications, we provide a comprehensive SDK that enables
+seamless data collection with rich native context. This SDK automatically
+collects 30+ device and app data points while maintaining privacy compliance
+and optimal performance.
 
-## ✨ Features
+## Installation
 
-- **📱 Rich Native Context**: Automatically collects 30+ device & app data points
-- **🔒 Privacy-First**: GDPR/CCPA compliant with optional device ID collection
-- **📶 Offline Queue**: Events are persisted and retried when network is available
-- **⚡ Lightweight**: Minimal impact on app size (~100KB total)
-- **🎯 Type-Safe**: Full TypeScript support with comprehensive type definitions
-- **📍 Auto Screen Tracking**: Optional helpers for Expo Router and React Navigation
-- **🔄 Graceful Fallback**: Works without native modules (Expo Go compatible)
-
-## 📦 Installation
-
-### Step 1: Install Package & Dependencies
+### Step 1: Install Package and Dependencies
 
 ```bash
 # npm
@@ -29,10 +22,9 @@ npx expo install react-native-edgee @react-native-async-storage/async-storage @r
 
 ### Step 2: Platform Setup
 
-Choose your platform setup:
+Choose your platform setup based on your React Native environment:
 
-<details>
-<summary><strong>📱 React Native CLI (Full Native Context)</strong></summary>
+#### React Native CLI
 
 **iOS:**
 ```bash
@@ -54,7 +46,7 @@ public class MainApplication extends Application implements ReactApplication {
     @SuppressWarnings("UnnecessaryLocalVariable")
     List<ReactPackage> packages = new PackageList(this).getPackages();
 
-    packages.add(new EdgeeReactNativePackage()); // 👈 Add this line
+    packages.add(new EdgeeReactNativePackage()); // Add this line
 
     return packages;
   }
@@ -75,10 +67,7 @@ public class MainApplication extends Application implements ReactApplication {
 npx react-native run-android
 ```
 
-</details>
-
-<details>
-<summary><strong>⚡ Expo Development Build (Full Native Context)</strong></summary>
+#### Expo Development Build
 
 ```bash
 # Install the package
@@ -89,20 +78,16 @@ npx expo run:ios     # For iOS
 npx expo run:android # For Android
 ```
 
-**Note:** Native modules require a development build, not Expo Go.
-
-</details>
+Note: Native modules require a development build, not Expo Go.
 
-<details>
-<summary><strong>📱 Expo Go (JavaScript Context Only)</strong></summary>
+#### Expo Go
 
 ```bash
 npx expo install react-native-edgee @react-native-async-storage/async-storage @react-native-community/netinfo
 ```
 
-**Limitations:** Native context collection is disabled. Only basic JavaScript context (screen size, platform, locale) will be available.
-
-</details>
+Limitations: Native context collection is disabled. Only basic JavaScript
+context (screen size, platform, locale) will be available.
 
 ### Step 3: Verify Installation
 
@@ -116,9 +101,7 @@ console.log('Native modules available:', isNativeModuleAvailable());
 // Should log: false (Expo Go)
 ```
 
-## 🚀 Quick Start
-
-### Basic Setup
+## Quick Start
 
 ```typescript
 import { EdgeeClient } from 'react-native-edgee';
@@ -126,12 +109,26 @@ import { EdgeeClient } from 'react-native-edgee';
 // Create client instance
 export const edgee = new EdgeeClient({
   host: "https://your-edgee-host.com",
-  debug: false, // Set to true if you want to enable debugging
+  debug: false, // Set to true to enable debug logging and debugger in the Edgee console
   collectDeviceId: false, // Set to true if you need unique device tracking
 });
 ```
 
-### Track Events
+Replace `https://your-edgee-host.com` with the URL provided in the Edgee
+console, in the project overview section.
+
+## Events
+
+### Screen event
+
+The `edgee.screen()` method expects the following parameters:
+
+field | type | description
+----- | ---- | ---
+`screen_obj` (required) | object | A free-form dictionary object containing properties of the `screen` event. This object has to include the `screen_name` field, and can include the `screen_class` and `properties` fields.
+`components` (optional) | object | Specifies which analytics components should receive the event data. This allows for targeted data sending based on your configured components within the Edgee platform.
+
+Example:
 
 ```typescript
 // Track screen views
@@ -143,16 +140,44 @@ edgee.screen({
     loaded_time: Date.now()
   }
 });
+```
+
+### Track event
+
+The `edgee.track()` method expects the following parameters:
 
-// Track events 
+field | type | description
+----- | ---- | ---
+`track_obj` (required) | object | A free-form dictionary object containing properties of the `track` event. This object has to include the `name` field, and can include the `screen_name` and `screen_class` fields, and the `properties` field.
+`components` (optional) | object | Specifies which analytics components should receive the event data. This allows for targeted data sending based on your configured components within the Edgee platform.
+
+Example:
+
+```typescript
+// Track events (automatically includes rich native context)
 edgee.track({
-  name: 'App Launched', // event name
+  name: 'App Launched',
+  screen_name: 'Home Screen',
+  screen_class: '/',
   properties: {
     source: 'cold_start',
     version: '1.0.0'
   }
 });
+```
+
+### User event
 
+The `edgee.user()` method expects the following parameters:
+
+field | type | description
+----- | ---- | ---
+`user_obj` (required) | object | A free-form dictionary object containing properties of the `user` event. This object has to include the `user_id` field, and can include the `properties` field.
+`components` (optional) | object | Specifies which analytics components should receive the event data. This allows for targeted data sending based on your configured components within the Edgee platform.
+
+Example:
+
+```typescript
 // Track user information
 edgee.user({
   user_id: '123',
@@ -163,11 +188,14 @@ edgee.user({
 });
 ```
 
-### Consent Management (Optional)
+### Consent (Optional)
+
+To define the consent status, you can use the `edgee.consent()` method.
 
 ```typescript
 // Set consent - all tracking calls automatically respect this setting
-await edgee.consent('granted'); // 'granted', 'denied', or 'pending'
+// 'granted', 'denied', or 'pending'
+await edgee.consent('granted');
 
 // Check consent status
 console.log('Current consent:', edgee.getConsent());
@@ -181,34 +209,7 @@ const unsubscribe = edgee.onConsentChange((status) => {
 await edgee.resetConsent();
 ```
 
-**Key Benefits:**
-- 🔒 **Transparent**: No need to check consent before each tracking call
-- 📡 **Auto-sync**: Consent events automatically sent to your Edgee server
-- 💾 **Persistent**: Consent preference stored locally and remembered
-- 🎯 **Compliant**: GDPR/CCPA ready with proper consent management
-
-## 📱 Rich Native Context
-
-With native modules enabled, each event automatically includes comprehensive context:
-
-### App Information
-- App name, version, build number
-- Bundle/package identifier
-- Installation and update timestamps
-
-### Device Information
-- Device model, manufacturer, brand
-- Screen dimensions, density, scale
-- Hardware capabilities (tablet, simulator/emulator detection)
-
-### System Information
-- OS name and version
-- Locale, language, country, timezone
-- Memory usage, storage info
-- Battery level and state (iOS)
-
-
-## ⚙️ Configuration
+## Configuration
 
 ```typescript
 interface EdgeeConfig {
@@ -219,59 +220,7 @@ interface EdgeeConfig {
 }
 ```
 
-
-## 🧪 Testing with EdgeeTestApp
-
-The repository includes a test app (`EdgeeTestApp/`) that allows you to quickly test the SDK functionality without integrating it into your own app.
-
-### Running the Test App
-
-1. **Navigate to the test app directory:**
-   ```bash
-   cd EdgeeTestApp
-   ```
-
-2. **Install dependencies:**
-   ```bash
-   npm install
-   # or
-   yarn install
-   ```
-
-3. **For iOS - Install pods:**
-   ```bash
-   cd ios && pod install && cd ..
-   ```
-
-4. **Start Metro bundler:**
-   ```bash
-   npm start
-   # or
-   yarn start
-   ```
-
-Then type i to launch an iOS app, or a for Android
-
-### Using the Test App
-
-The test app provides a simple UI to test all SDK features:
-
-1. **Set Edgee Host**: Enter your Edgee endpoint URL (defaults to `https://demo.edgee.app`)
-   - Click "Init" to initialize the SDK with your host
-
-2. **Test Events**:
-   - **Track Event**: Enter an event name and click "Track Event" to send a track event
-   - **Screen Event**: Click "Screen Event" to track a screen view
-   - **User Event**: Click "User Event" to send user identification data
-
-3. **Test Consent Management**:
-   - Click "Pending", "Granted", or "Denied" to set consent status
-   - Click "Get Consent" to view the current consent status
-
-4. **Monitor Status**: The status bar at the bottom shows the result of each action
-
-
-### Debug Mode
+## Debug Mode
 
 Enable debug logging to see what's happening:
 
@@ -282,33 +231,24 @@ const edgee = new EdgeeClient({
 });
 ```
 
-## 📋 Compatibility
+## Compatibility
 
 | Platform | Version | Native Context | Auto-Linking |
 |----------|---------|----------------|--------------|
-| **React Native** | 0.72+ | ✅ Full | iOS: ✅ Android: Manual |
-| **iOS** | 11.0+ | ✅ Full | ✅ CocoaPods |
-| **Android** | API 21+ | ✅ Full | ⚠️ Manual setup |
-| **Expo Dev Build** | Latest | ✅ Full | ✅ Automatic |
-| **Expo Go** | Latest | ⚠️ Fallback | N/A |
-
-## 📚 TypeScript Support
-
-Full TypeScript support with comprehensive type definitions:
-
-```typescript
-import type {
-  EdgeeNativeContext,
-  EdgeeClientContext,
-  EdgeeConfig
-} from 'react-native-edgee';
-```
+| React Native | 0.72+ | Full | iOS: Yes, Android: Manual |
+| iOS | 11.0+ | Full | CocoaPods |
+| Android | API 21+ | Full | Manual setup |
+| Expo Dev Build | Latest | Full | Automatic |
+| Expo Go | Latest | Fallback | N/A |
 
-## 📄 License
+## Next Steps
 
-MIT
+After integrating the React Native SDK, you are ready to start using Edgee's
+services.
 
-## 🆘 Support
+In the Services section, you will find guides on activating and customizing
+features such as advanced analytics, A/B testing, security, and more:
+https://www.edgee.cloud/docs/proxy/services/overview
 
-- **Issues**: [GitHub Issues](https://github.com/edgee-cloud/react-native-edgee/issues)
-- **Documentation**: [Edgee Docs](https://www.edgee.cloud/docs)
+For more details about the React Native SDK, visit:
+https://github.com/edgee-cloud/react-native-edgee

package/dist/core/queue.js

@@ -25,8 +25,14 @@ class EventQueue {
             this.online = !!state.isConnected && !!state.isInternetReachable;
         });
         void edgee_store_1.edgeeStore.getPendingEvents().then((events) => {
-            this.q = events;
+            // Merge persisted events with any events that were added during initialization
+            // to avoid losing events due to race conditions
+            const existingEvents = this.q;
+            this.q = [...events, ...existingEvents];
             this.ready = true;
+            // Trigger flush now that we're ready
+            if (this.shouldFlush())
+                void this.flush();
         });
     }
     destroy() {
@@ -41,8 +47,9 @@ class EventQueue {
     enqueue(item) {
         this.q.push(item);
         void edgee_store_1.edgeeStore.addEvent(item);
-        if (this.shouldFlush())
+        if (this.shouldFlush()) {
             void this.flush();
+        }
     }
     /**
      * Send a direct payload (used for consent events)
@@ -66,26 +73,32 @@ class EventQueue {
         return this.ready && this.online && this.q.length > 0;
     }
     async flush() {
-        if (this.flushing || !this.shouldFlush())
+        if (this.flushing || !this.shouldFlush()) {
             return;
+        }
         this.flushing = true;
-        const items = [...this.q];
+        // Take items from the queue atomically using splice
+        // This prevents losing events that are added during flush
+        const itemsToFlush = this.q.splice(0, this.q.length);
+        (0, utils_1.log)(this.config, `Flushing ${itemsToFlush.length} event(s)...`);
         try {
-            for (const item of items) {
+            for (const item of itemsToFlush) {
                 await (0, api_1.uploadEvent)(this.config, item);
+                (0, utils_1.log)(this.config, `Event sent: ${item.type} - ${item.data.name || 'user'}`);
             }
-            this.q = [];
+            // Only clear persisted events after successful send
             await edgee_store_1.edgeeStore.clearEvents();
         }
         catch (error) {
             (0, utils_1.logError)("Error processing event batch.", error);
-            this.q = [];
-            await edgee_store_1.edgeeStore.clearEvents();
+            // On error, re-add failed items to the front of the queue for retry
+            this.q.unshift(...itemsToFlush);
         }
         finally {
             this.flushing = false;
+            // Drain any events that were added during flush
             if (this.shouldFlush())
-                void this.flush(); // Drain if new items arrived
+                void this.flush();
         }
     }
 }

package/dist/index.js

@@ -64,6 +64,7 @@ class EdgeeClient {
         }
         const event = (0, api_1.createScreenEvent)(restData, components, context);
         this.queue.enqueue(event);
+        (0, utils_1.log)(this.config, "SCREEN event queued:", screen_name);
     }
     /**
      * Track a custom event
@@ -83,6 +84,7 @@ class EdgeeClient {
         }
         const event = (0, api_1.createTrackEvent)(restData, components, context);
         this.queue.enqueue(event);
+        (0, utils_1.log)(this.config, "TRACK event queued:", data.name);
     }
     /**
      * Track a user event
@@ -91,6 +93,7 @@ class EdgeeClient {
         const context = await (0, context_1.getContext)(this.config);
         const event = (0, api_1.createUserEvent)(data, components, context);
         this.queue.enqueue(event);
+        (0, utils_1.log)(this.config, "USER event queued:", data.user_id || data.anonymous_id || "anonymous");
     }
     /**
      * Send consent event directly to Edgee (matches web SDK format)

package/dist/native-context.js

@@ -37,7 +37,10 @@ async function getNativeContext(collectDeviceId) {
     if (contextPromise) {
         return contextPromise;
     }
-    contextPromise = EdgeeReactNative.getContextInfo(collectDeviceId)
+    const config = {
+        collectDeviceId: collectDeviceId,
+    };
+    contextPromise = EdgeeReactNative.getContextInfo(config)
         .then((context) => {
         cachedContext = context;
         contextPromise = null;

package/dist/types.d.ts

@@ -1,4 +1,7 @@
 import { NativeModule } from "react-native";
+export interface EdgeeNativeContextConfig {
+    collectDeviceId?: boolean;
+}
 export interface EdgeeNativeContext {
     appName: string;
     appVersion: string;
@@ -57,5 +60,5 @@ export interface EdgeeNativeContext {
     lastUpdateTime?: number;
 }
 export interface EdgeeReactNativeModule extends NativeModule {
-    getContextInfo(collectDeviceId: boolean): Promise<EdgeeNativeContext>;
+    getContextInfo(config: EdgeeNativeContextConfig): Promise<EdgeeNativeContext>;
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "react-native-edgee",
-  "version": "1.0.7",
+  "version": "1.0.9",
   "description": "Lightweight Edgee data collection client for React Native with native context collection.",
   "license": "MIT",
   "main": "dist/index.js",