react-native-edgee 1.0.0

package/README.md

@@ -0,0 +1,427 @@
+# react-native-edgee
+
+Lightweight Edgee data collection client for React Native with comprehensive native context collection.
+
+## ✨ Features
+
+- **📱 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
+
+```bash
+# npm
+npm install react-native-edgee @react-native-async-storage/async-storage @react-native-community/netinfo
+
+# yarn
+yarn add react-native-edgee @react-native-async-storage/async-storage @react-native-community/netinfo
+
+# Expo
+npx expo install react-native-edgee @react-native-async-storage/async-storage @react-native-community/netinfo
+```
+
+### Step 2: Platform Setup
+
+Choose your platform setup:
+
+<details>
+<summary><strong>📱 React Native CLI (Full Native Context)</strong></summary>
+
+**iOS:**
+```bash
+cd ios && pod install && cd ..
+```
+
+**Android:**
+
+1. **Add native module** to `android/app/src/main/java/.../MainApplication.java`:
+
+```java
+import com.reactnativeedgee.EdgeeReactNativePackage;
+
+public class MainApplication extends Application implements ReactApplication {
+  // ... existing code ...
+
+  @Override
+  protected List<ReactPackage> getPackages() {
+    @SuppressWarnings("UnnecessaryLocalVariable")
+    List<ReactPackage> packages = new PackageList(this).getPackages();
+
+    packages.add(new EdgeeReactNativePackage()); // 👈 Add this line
+
+    return packages;
+  }
+}
+```
+
+2. **Add permission** to `android/app/src/main/AndroidManifest.xml`:
+
+```xml
+<manifest xmlns:android="http://schemas.android.com/apk/res/android">
+    <uses-permission android:name="android.permission.ACCESS_NETWORK_STATE" />
+    <!-- Your existing manifest content -->
+</manifest>
+```
+
+3. **Rebuild your app:**
+```bash
+npx react-native run-android
+```
+
+</details>
+
+<details>
+<summary><strong>⚡ Expo Development Build (Full Native Context)</strong></summary>
+
+```bash
+# Install the package
+npx expo install react-native-edgee @react-native-async-storage/async-storage @react-native-community/netinfo
+
+# Create development build (this compiles native modules)
+npx expo run:ios     # For iOS
+npx expo run:android # For Android
+```
+
+**Note:** Native modules require a development build, not Expo Go.
+
+</details>
+
+<details>
+<summary><strong>📱 Expo Go (JavaScript Context Only)</strong></summary>
+
+```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>
+
+### Step 3: Verify Installation
+
+Test that native modules are working:
+
+```typescript
+import { isNativeModuleAvailable } from 'react-native-edgee';
+
+console.log('Native modules available:', isNativeModuleAvailable());
+// Should log: true (React Native CLI, Expo Dev Build)
+// Should log: false (Expo Go)
+```
+
+## 🚀 Quick Start
+
+### Basic Setup
+
+```typescript
+import { EdgeeClient } from 'react-native-edgee';
+
+// Create client instance
+export const edgee = new EdgeeClient({
+  host: "https://your-edgee-host.com",
+  debug: __DEV__, // Enable debug logging in development
+  collectDeviceId: false, // Set to true if you need unique device tracking
+});
+```
+
+### Track Events
+
+```typescript
+// Track events (automatically includes rich native context)
+// Consent is handled transparently - no need to check before each call!
+edgee.track('App Launched', {
+  source: 'cold_start',
+  version: '1.0.0'
+});
+
+// Track user information
+edgee.user({
+  id: '123',
+  email: 'user@example.com',
+  plan: 'premium'
+});
+
+// Track screen views
+edgee.screen('Home Screen', {
+  category: 'main',
+  loaded_time: Date.now()
+});
+```
+
+### Consent Management (Optional)
+
+```typescript
+// Set consent - all tracking calls automatically respect this setting
+await edgee.setConsent('granted'); // 'granted', 'denied', or 'pending'
+
+// Check consent status
+console.log('Current consent:', edgee.getConsent());
+console.log('Can track:', edgee.canTrack());
+
+// Listen for consent changes
+const unsubscribe = edgee.onConsentChange((status) => {
+  console.log('Consent changed to:', status);
+});
+
+// Reset consent
+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)
+
+### Network Information
+- Connection type (WiFi, cellular, ethernet)
+- Carrier name and network codes
+- Radio technology (3G, 4G, 5G)
+
+### Privacy Information *(Optional)*
+- Advertising ID (with proper consent on iOS 14+)
+- Device ID (privacy-compliant, opt-in only)
+- Tracking authorization status
+
+## ⚛️ React Integration
+
+### Context Provider (Optional)
+
+```typescript
+import { EdgeeProvider, useEdgee } from 'react-native-edgee';
+
+// Wrap your app
+export default function App() {
+  return (
+    <EdgeeProvider host="https://your-edgee-host.com" debug={__DEV__}>
+      <YourApp />
+    </EdgeeProvider>
+  );
+}
+
+// Use in components
+function SomeComponent() {
+  const edgee = useEdgee();
+
+  const handleButtonPress = () => {
+    // Tracking automatically respects consent - no need to check!
+    edgee.track('Button Pressed', { button_id: 'cta_main' });
+  };
+
+  const handleConsentGrant = async () => {
+    await edgee.setConsent('granted');
+  };
+
+  return (
+    <View>
+      <Button onPress={handleButtonPress} title="Track Me" />
+      <Button onPress={handleConsentGrant} title="Grant Consent" />
+    </View>
+  );
+}
+```
+
+### Auto Screen Tracking
+
+<details>
+<summary><strong>Expo Router</strong></summary>
+
+```typescript
+import { EdgeeAutoTracker } from 'react-native-edgee';
+
+export default function RootLayout() {
+  return (
+    <>
+      <EdgeeAutoTracker edgee={edgee} />
+      <Stack>
+        <Stack.Screen name="index" />
+        <Stack.Screen name="profile" />
+      </Stack>
+    </>
+  );
+}
+```
+
+</details>
+
+<details>
+<summary><strong>React Navigation</strong></summary>
+
+```typescript
+import { navigation } from 'react-native-edgee';
+
+const navigationRef = useRef();
+
+return (
+  <NavigationContainer
+    ref={navigationRef}
+    onStateChange={() => {
+      navigation.trackScreenChange(navigationRef, edgee);
+    }}
+  >
+    {/* Your navigation structure */}
+  </NavigationContainer>
+);
+```
+
+</details>
+
+## ⚙️ Configuration
+
+```typescript
+interface EdgeeConfig {
+  host: string;                    // Your Edgee endpoint URL (required)
+  debug?: boolean;                 // Enable debug logging (default: false)
+  collectDeviceId?: boolean;       // Collect unique device ID (default: false)
+}
+```
+
+### Privacy Considerations
+
+- **Device ID Collection**: Only enable `collectDeviceId: true` if you need persistent device tracking
+- **iOS Advertising ID**: Automatically respects App Tracking Transparency (iOS 14+)
+- **GDPR/CCPA Compliance**: All sensitive data collection is optional and clearly documented
+
+## 🔧 Advanced Usage
+
+### Manual Native Context Access
+
+```typescript
+import { getNativeContext, isNativeModuleAvailable } from 'react-native-edgee';
+
+// Check if native modules are available
+if (isNativeModuleAvailable()) {
+  const context = await getNativeContext({ collectDeviceId: false });
+  console.log('Device model:', context.model);
+  console.log('Is tablet:', context.isTablet);
+  console.log('Network type:', context.networkType);
+  console.log('Total memory:', context.totalMemoryMB);
+}
+```
+
+### Context Caching
+
+```typescript
+import { clearContextCache } from 'react-native-edgee';
+
+// Clear cached context (useful for testing or when context might change)
+clearContextCache();
+```
+
+## 🔍 Troubleshooting
+
+### Common Issues
+
+<details>
+<summary><strong>"Module not found" Error</strong></summary>
+
+**iOS:**
+```bash
+cd ios && rm -rf build && pod install && cd ..
+npx react-native run-ios
+```
+
+**Android:**
+- Ensure `EdgeeReactNativePackage` is added to `MainApplication.java`
+- Clean build: `cd android && ./gradlew clean && cd ..`
+
+</details>
+
+<details>
+<summary><strong>No Native Context in Events</strong></summary>
+
+1. Check if native modules are available:
+   ```typescript
+   console.log('Available:', isNativeModuleAvailable());
+   ```
+
+2. If `false`, verify platform setup above
+3. In Expo Go, this is expected (use Expo Development Build)
+
+</details>
+
+<details>
+<summary><strong>Build Errors</strong></summary>
+
+**Clean everything:**
+```bash
+# React Native CLI
+cd ios && rm -rf build && cd ..
+cd android && ./gradlew clean && cd ..
+npx react-native start --reset-cache
+
+# Expo
+npx expo run:ios --clear-cache
+```
+
+</details>
+
+### Debug Mode
+
+Enable debug logging to see what's happening:
+
+```typescript
+const edgee = new EdgeeClient({
+  host: "https://your-edgee-host.com",
+  debug: true, // This will log all events and native context
+});
+```
+
+## 📋 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';
+```
+
+## 📄 License
+
+MIT
+
+## 🆘 Support
+
+- **Issues**: [GitHub Issues](https://github.com/edgee-cloud/react-native-edgee/issues)
+- **Documentation**: [Edgee Docs](https://docs.edgee.cloud)
+- **Community**: [Edgee Discord](https://discord.gg/edgee)

package/android/build.gradle

@@ -0,0 +1,120 @@
+buildscript {
+  repositories {
+    google()
+    mavenCentral()
+  }
+
+  dependencies {
+    classpath "com.android.tools.build:gradle:7.2.1"
+  }
+}
+
+apply plugin: "com.android.library"
+
+def getExtOrDefault(name) {
+  return rootProject.ext.has(name) ? rootProject.ext.get(name) : project.properties["ReactNativeEdgee_" + name]
+}
+
+def getExtOrIntegerDefault(name) {
+  return rootProject.ext.has(name) ? rootProject.ext.get(name) : (project.properties["ReactNativeEdgee_" + name]).toInteger()
+}
+
+android {
+  compileSdkVersion getExtOrIntegerDefault("compileSdkVersion")
+
+  defaultConfig {
+    minSdkVersion getExtOrIntegerDefault("minSdkVersion")
+    targetSdkVersion getExtOrIntegerDefault("targetSdkVersion")
+    versionCode 1
+    versionName "1.0"
+  }
+
+  buildTypes {
+    release {
+      minifyEnabled false
+    }
+  }
+
+  lintOptions {
+    disable "GradleCompatible"
+  }
+
+  compileOptions {
+    sourceCompatibility JavaVersion.VERSION_1_8
+    targetCompatibility JavaVersion.VERSION_1_8
+  }
+}
+
+repositories {
+  mavenCentral()
+  google()
+
+  def found = false
+  def defaultDir = null
+  def androidSourcesName = "React Native sources"
+
+  if (rootProject.ext.has("reactNativeAndroidRoot")) {
+    defaultDir = rootProject.ext.get("reactNativeAndroidRoot")
+  } else {
+    defaultDir = new File(
+      projectDir,
+      "/../../../node_modules/react-native/android"
+    )
+  }
+
+  if (defaultDir.exists()) {
+    maven {
+      url defaultDir.toString()
+      name androidSourcesName
+    }
+
+    logger.info(":${project.name}:reactNativeAndroidRoot ${defaultDir.canonicalPath}")
+    found = true
+  } else {
+    def parentDir = rootProject.projectDir
+
+    1.upto(5, {
+      if (found) return true
+      parentDir = parentDir.parentFile
+
+      def androidSourcesDir = new File(
+        parentDir,
+        "node_modules/react-native"
+      )
+
+      def androidPrebuiltBinaryDir = new File(
+        parentDir,
+        "node_modules/react-native/android"
+      )
+
+      if (androidPrebuiltBinaryDir.exists()) {
+        maven {
+          url androidPrebuiltBinaryDir.toString()
+          name androidSourcesName
+        }
+
+        logger.info(":${project.name}:reactNativeAndroidRoot ${androidPrebuiltBinaryDir.canonicalPath}")
+        found = true
+      } else if (androidSourcesDir.exists()) {
+        maven {
+          url androidSourcesDir.toString()
+          name androidSourcesName
+        }
+
+        logger.info(":${project.name}:reactNativeAndroidRoot ${androidSourcesDir.canonicalPath}")
+        found = true
+      }
+    })
+  }
+
+  if (!found) {
+    throw new GradleException(
+      "${project.name}: unable to locate React Native android sources. " +
+      "Ensure you have you installed React Native as a dependency in your project and try again."
+    )
+  }
+}
+
+dependencies {
+  implementation "com.facebook.react:react-native:+"
+}

package/android/src/main/AndroidManifest.xml

@@ -0,0 +1,4 @@
+<manifest xmlns:android="http://schemas.android.com/apk/res/android"
+          package="com.reactnativeedgee">
+    <uses-permission android:name="android.permission.ACCESS_NETWORK_STATE" />
+</manifest>