@datalyr/react-native 1.1.1 → 1.2.0

package/EXPO_INSTALL.md

@@ -1,297 +0,0 @@
-# Datalyr Expo SDK - Installation Guide
-
-## Expo Compatibility
-
-The Datalyr SDK works with all Expo workflows:
-
-- **Expo Bare Workflow** - Full compatibility (use regular React Native SDK)
-- **Expo Managed Workflow** - Requires Expo-specific setup (this guide)
-- **Expo Go** - Limited compatibility due to native dependencies
-
-## Quick Setup for Expo Managed Workflow
-
-### 1. Install Expo Dependencies
-
-```bash
-# Navigate to your Expo project
-cd your-expo-app
-
-# Install Expo-compatible dependencies
-npx expo install @react-native-async-storage/async-storage
-npx expo install expo-application
-npx expo install expo-constants  
-npx expo install expo-device
-npx expo install expo-network
-npx expo install expo-tracking-transparency
-npx expo install react-native-get-random-values
-
-# Install additional dependencies
-npm install uuid
-npm install --save-dev @types/uuid
-```
-
-### 2. Update app.json/app.config.js
-
-Add required permissions and configuration:
-
-```json
-{
-  "expo": {
-    "name": "Your App",
-    "version": "1.0.0",
-    "permissions": [
-      "INTERNET",
-      "ACCESS_NETWORK_STATE"
-    ],
-    "ios": {
-      "infoPlist": {
-        "NSUserTrackingUsageDescription": "This app uses tracking to provide personalized ads and analytics.",
-        "CFBundleURLTypes": [
-          {
-            "CFBundleURLName": "your.app.identifier",
-            "CFBundleURLSchemes": ["yourappscheme"]
-          }
-        ]
-      }
-    },
-    "android": {
-      "permissions": [
-        "INTERNET",
-        "ACCESS_NETWORK_STATE"
-      ],
-      "intentFilters": [
-        {
-          "action": "VIEW",
-          "autoVerify": true,
-          "data": [
-            {
-              "scheme": "yourappscheme"
-            }
-          ],
-          "category": [
-            "BROWSABLE",
-            "DEFAULT"
-          ]
-        }
-      ]
-    }
-  }
-}
-```
-
-### 3. Copy Expo-Compatible SDK Files
-
-```bash
-# Create SDK directory
-mkdir -p src/datalyr-sdk
-
-# Copy the Expo-compatible files
-# You'll need to create these based on the original SDK but using Expo APIs
-```
-
-### 4. Initialize in Your Expo App
-
-```typescript
-// App.tsx
-import React, { useEffect } from 'react';
-import 'react-native-get-random-values'; // Important: Must be imported first
-import { datalyr } from '@datalyr/react-native-sdk';
-
-const App: React.FC = () => {
-  useEffect(() => {
-    initializeDatalyr();
-  }, []);
-
-  const initializeDatalyr = async () => {
-    try {
-      await datalyr.initialize({
-        workspaceId: 'ozLZblQ8hN', // Your workspace ID
-        apiKey: 'dk_your_api_key', // Required for authentication
-        debug: true,
-        enableAttribution: true,    // ✅ Deep link attribution tracking
-        autoEvents: {
-          trackSessions: true,          // ✅ Automatic session tracking
-          trackScreenViews: true,       // ✅ Automatic screen tracking  
-          trackAppUpdates: true,        // ✅ App version changes
-          trackPerformance: true,       // ✅ App launch time, performance
-          sessionTimeoutMs: 30 * 60 * 1000, // 30 minutes
-        },
-      });
-      
-      console.log('Datalyr Expo SDK initialized with auto-events!');
-    } catch (error) {
-      console.error('SDK init failed:', error);
-    }
-  };
-
-  // ... rest of your app
-};
-
-export default App;
-```
-
-## Expo vs React Native CLI Differences
-
-| Feature | React Native CLI | Expo Managed | Expo Bare |
-|---------|------------------|--------------|-----------|
-| Device Info | `react-native-device-info` | `expo-device` + `expo-application` | `react-native-device-info` |
-| IDFA/GAID | `react-native-idfa` | `expo-tracking-transparency` + setup | `react-native-idfa` |
-| Network Detection | `@react-native-community/netinfo` | `expo-network` | `@react-native-community/netinfo` |
-| Storage | `@react-native-async-storage/async-storage` | Same ✅ | Same ✅ |
-| Attribution | Full support ✅ | Full support ✅ | Full support ✅ |
-| Auto Events | Full support ✅ | Full support ✅ | Full support ✅ |
-
-## Expo-Specific Features
-
-### 1. Device Information
-```typescript
-// Uses expo-device and expo-application instead of react-native-device-info
-import * as Device from 'expo-device';
-import * as Application from 'expo-application';
-
-const deviceInfo = {
-  model: Device.modelName,
-  manufacturer: Device.manufacturer,
-  osVersion: Device.osVersion,
-  appVersion: Application.nativeApplicationVersion,
-  buildNumber: Application.nativeBuildVersion,
-  bundleId: Application.applicationId,
-  isEmulator: !Device.isDevice,
-};
-```
-
-### 2. IDFA Permission (iOS)
-```typescript
-// Uses expo-tracking-transparency for iOS IDFA permission
-import * as TrackingTransparency from 'expo-tracking-transparency';
-
-const requestIDFAPermission = async () => {
-  if (Platform.OS === 'ios') {
-    const { status } = await TrackingTransparency.requestTrackingPermissionsAsync();
-    return status === TrackingTransparency.PermissionStatus.GRANTED;
-  }
-  return false;
-};
-```
-
-### 3. Network Detection
-```typescript
-// Uses expo-network instead of @react-native-community/netinfo
-import * as Network from 'expo-network';
-
-const getNetworkType = async () => {
-  const networkState = await Network.getNetworkStateAsync();
-  return networkState.type; // 'WIFI', 'CELLULAR', etc.
-};
-```
-
-## Attribution Setup for Expo
-
-Deep links work the same way, but configuration is in `app.json`:
-
-### Test URLs (Same as React Native)
-```typescript
-// Test with Datalyr LYR tags
-const lyrUrl = 'yourappscheme://open?lyr=expo_campaign&utm_source=facebook&fbclid=abc123';
-
-// Test Facebook attribution  
-const facebookUrl = 'yourappscheme://open?utm_source=facebook&utm_campaign=summer_sale&fbclid=IwAR123abc';
-
-// Test TikTok attribution
-const tiktokUrl = 'yourappscheme://open?utm_source=tiktok&utm_campaign=viral_video&ttclid=tiktok123xyz';
-
-// Test Google attribution
-const googleUrl = 'yourappscheme://open?utm_source=google&utm_campaign=brand_search&gclid=google456def';
-```
-
-## Testing with Expo
-
-### Development
-```bash
-# Start Expo development server
-npx expo start
-
-# Test on device/simulator
-npx expo start --ios
-npx expo start --android
-```
-
-### Production Testing
-```bash
-# Build for testing
-eas build --platform ios --profile preview
-eas build --platform android --profile preview
-
-# Submit to stores
-eas submit --platform ios
-eas submit --platform android
-```
-
-## Expo Limitations
-
-### What Works:
-- Event tracking and attribution
-- Session management  
-- Screen view tracking
-- App lifecycle events
-- Deep link attribution
-- Basic device fingerprinting
-
-### Limitations:
-- **IDFA/GAID Collection** - Requires additional setup
-- **Advanced Device Info** - Some properties not available in managed workflow
-- **Carrier Information** - Not available in managed workflow
-- **Custom Native Modules** - Not available in managed workflow
-
-## Recommended Setup
-
-### For Maximum Compatibility:
-1. **Use Expo Bare Workflow** - Get full React Native CLI features
-2. **Or use regular React Native CLI** - Best for attribution tracking
-
-### For Managed Workflow:
-1. **Accept some limitations** - IDFA/GAID might need additional setup  
-2. **Core attribution still works** - LYR tags, UTM params, click IDs
-3. **Automatic events work fully** - Sessions, screen views, app lifecycle
-
-## Expected Events in Dashboard
-
-Events will appear in your Datalyr dashboard with `source: 'mobile_app'`:
-
-**Automatic Events:**
-- `session_start` - New user session
-- `session_end` - Session ended with stats  
-- `pageviews` - Screen navigation
-- `app_install` - First app launch with attribution
-- `app_update` - App version changes
-- `app_foreground`/`app_background` - App lifecycle
-- `sdk_initialized` - SDK setup complete
-
-**Manual Events:**
-- Custom events from `datalyr.track()`
-- User identification from `datalyr.identify()`
-
-## Choosing Between Expo and React Native CLI
-
-### Choose **React Native CLI** if:
-- You need full IDFA/GAID support
-- You want maximum attribution accuracy  
-- You're comfortable with native development
-- You need custom native modules
-
-### Choose **Expo Managed** if:
-- You want easier development and deployment
-- Core attribution (LYR tags, UTM, click IDs) is sufficient
-- You're okay with some device fingerprinting limitations
-- You prioritize development speed over maximum tracking
-
-### Choose **Expo Bare** if:
-- You want the best of both worlds
-- You can use the full React Native CLI SDK
-- You like Expo's build and deployment tools
-
----
-
-**Ready to test?** Your Expo app with automatic attribution is ready!
-
-The SDK provides 90% of the attribution value even with Expo's managed workflow limitations. 

package/INSTALL.md

@@ -1,402 +0,0 @@
-# Datalyr React Native SDK - Installation Guide
-
-## Key Features
-
-- **Complete Attribution** - Track users from ad click to conversion
-- **Automatic Events** - Sessions, screen views, app lifecycle
-- **SKAdNetwork Support** - iOS 14+ attribution
-- **Offline Support** - Queue events when offline
-- **Deep Link Support** - Extract attribution from app launches
-- **Privacy Compliant** - GDPR/CCPA support
-
-## Quick Setup
-
-### 1. Install Package
-
-```bash
-npm install @datalyr/react-native
-# or
-yarn add @datalyr/react-native
-```
-
-### 2. iOS Setup (if targeting iOS)
-
-```bash
-cd ios && pod install && cd ..
-```
-
-### 3. Initialize in Your App
-
-**Basic Setup:**
-```typescript
-// App.tsx or your main component
-import React, { useEffect } from 'react';
-import { datalyr } from '@datalyr/react-native-sdk';
-
-const App: React.FC = () => {
-  useEffect(() => {
-    initializeDatalyr();
-  }, []);
-
-  const initializeDatalyr = async () => {
-    try {
-      await datalyr.initialize({
-        workspaceId: 'ozLZblQ8hN', // Your workspace ID
-        apiKey: 'dk_your_api_key', // Required for authentication
-        debug: true,
-        enableAttribution: true,    // ✅ Deep link attribution tracking
-        autoEvents: {
-          trackSessions: true,          // ✅ Automatic session tracking
-          trackScreenViews: true,       // ✅ Automatic screen tracking  
-          trackAppUpdates: true,        // ✅ App version changes
-          trackPerformance: true,       // ✅ App launch time, performance
-          sessionTimeoutMs: 30 * 60 * 1000, // 30 minutes
-        },
-      });
-      
-      // Manual events still work (but many are now automatic!)
-      await datalyr.track('app_launch');
-      
-      console.log('Datalyr SDK initialized with auto-events!');
-    } catch (error) {
-      console.error('SDK init failed:', error);
-    }
-  };
-
-  // ... rest of your app
-};
-```
-
-**SKAdNetwork Setup (iOS 14+ Attribution):**
-```typescript
-// For iOS attribution competing with AppsFlyer/Adjust
-import React, { useEffect } from 'react';
-import { Datalyr } from '@datalyr/react-native-sdk';
-
-const App: React.FC = () => {
-  useEffect(() => {
-    initializeDatalyrWithSKAdNetwork();
-  }, []);
-
-  const initializeDatalyrWithSKAdNetwork = async () => {
-    try {
-      await Datalyr.initialize({
-        workspaceId: 'your-workspace-id',
-        apiKey: 'dk_your_api_key',
-        skadTemplate: 'ecommerce', // Choose: 'ecommerce', 'gaming', 'subscription'
-        debug: true,
-        enableAttribution: true,
-        autoEvents: {
-          trackSessions: true,
-          trackScreenViews: true,
-        },
-      });
-      
-      console.log('Datalyr SDK initialized with SKAdNetwork!');
-    } catch (error) {
-      console.error('SDK init failed:', error);
-    }
-  };
-
-  // ... rest of your app
-};
-```
-
-### 5. Test the Integration
-
-```typescript
-// Test tracking events
-const testTracking = async () => {
-  // Track a purchase
-  await datalyr.track('purchase', {
-    value: 29.99,
-    currency: 'USD',
-    item_id: 'test_product'
-  });
-
-  // Identify a user
-  await datalyr.identify('user_123', {
-    email: 'test@example.com',
-    name: 'Test User'
-  });
-
-  // Track screen view
-  await datalyr.screen('home_screen');
-};
-```
-
-## Configuration Options
-
-```typescript
-await datalyr.initialize({
-  workspaceId: 'your-workspace-id',     // Required
-  apiKey: 'dk_your_api_key',            // Required for authentication
-  debug: true,                          // Enable debug logs
-  endpoint: 'custom-endpoint',          // Optional custom endpoint
-  maxRetries: 3,                        // Network retry attempts
-  retryDelay: 1000,                     // Retry delay in ms
-  batchSize: 10,                        // Events per batch
-  flushInterval: 10000,                 // Auto-flush interval in ms
-  maxQueueSize: 100,                    // Max offline queue size
-  
-  // 🚀 NEW: SKAdNetwork Support (iOS 14+ Attribution)
-  skadTemplate: 'ecommerce',            // Choose: 'ecommerce', 'gaming', 'subscription'
-  
-  // 🚀 NEW: Automatic Events (Like Mixpanel)
-  autoEvents: {
-    trackSessions: true,                // Session start/end tracking
-    trackScreenViews: true,             // Automatic screen view events
-    trackAppUpdates: true,              // App version change detection
-    trackPerformance: true,             // App launch performance tracking
-    sessionTimeoutMs: 30 * 60 * 1000,  // Session timeout (30 minutes)
-  },
-});
-```
-
-## Platform Requirements
-
-- **React Native**: >= 0.60.0
-- **iOS**: >= 11.0
-- **Android**: >= API level 21
-
-## Framework Compatibility
-
-| Framework | Compatibility | Install Guide |
-|-----------|---------------|---------------|
-| **React Native CLI** | ✅ Full Support | This guide |
-| **Expo Bare Workflow** | ✅ Full Support | This guide |
-| **Expo Managed Workflow** | ✅ Supported* | [EXPO_INSTALL.md](./EXPO_INSTALL.md) |
-| **Expo Go** | ⚠️ Limited | Use managed workflow |
-
-*\*Expo managed workflow has some limitations (IDFA/GAID collection requires additional setup)*
-
-**📖 For Expo users:** See [EXPO_INSTALL.md](./EXPO_INSTALL.md) for Expo-specific setup instructions.
-
-## Setting Up Attribution
-
-### 1. Configure Deep Links
-
-Add URL scheme to your app to handle attribution links:
-
-**iOS (ios/YourApp/Info.plist):**
-```xml
-<key>CFBundleURLTypes</key>
-<array>
-  <dict>
-    <key>CFBundleURLName</key>
-    <string>your.app.identifier</string>
-    <key>CFBundleURLSchemes</key>
-    <array>
-      <string>yourappscheme</string>
-    </array>
-  </dict>
-</array>
-```
-
-**Android (android/app/src/main/AndroidManifest.xml):**
-```xml
-<activity
-  android:name=".MainActivity"
-  android:exported="true"
-  android:launchMode="singleTop">
-  
-  <intent-filter android:autoVerify="true">
-    <action android:name="android.intent.action.VIEW" />
-    <category android:name="android.intent.category.DEFAULT" />
-    <category android:name="android.intent.category.BROWSABLE" />
-    <data android:scheme="yourappscheme" />
-  </intent-filter>
-</activity>
-```
-
-### 2. Test Attribution
-
-```typescript
-// Test with Datalyr LYR tags (RECOMMENDED!)
-const lyrUrl = 'yourappscheme://open?lyr=mobile_campaign_q4&utm_source=facebook&utm_medium=paid_social&utm_campaign=summer_sale&fbclid=IwAR123abc';
-
-// Test Facebook attribution
-const facebookUrl = 'yourappscheme://open?utm_source=facebook&utm_medium=paid_social&utm_campaign=summer_sale&fbclid=IwAR123abc&lyr=fb_summer_2024';
-
-// Test TikTok attribution  
-const tiktokUrl = 'yourappscheme://open?utm_source=tiktok&utm_medium=video&utm_campaign=viral_video&ttclid=tiktok123xyz&lyr=tt_viral_campaign';
-
-// Test Google attribution
-const googleUrl = 'yourappscheme://open?utm_source=google&utm_medium=search&utm_campaign=brand_search&gclid=google456def&lyr=google_brand_search';
-
-// Test Partner attribution
-const partnerUrl = 'yourappscheme://open?utm_source=partner&partner_id=partner123&affiliate_id=aff456&lyr=partner_campaign_q4';
-
-// Get attribution data
-const attributionData = datalyr.getAttributionData();
-console.log('Attribution:', attributionData);
-/*
-Expected output:
-{
-  lyr: "mobile_campaign_q4",
-  utm_source: "facebook", 
-  campaign_source: "facebook",
-  utm_campaign: "summer_sale",
-  campaign_name: "summer_sale", 
-  fbclid: "IwAR123abc",
-  install_time: "2024-01-01T00:00:00Z"
-}
-*/
-```
-
-## Testing Events
-
-After setup, events will appear in your Datalyr dashboard at:
-`https://app.datalyr.com/dashboard/ozLZblQ8hN`
-
-Look for events with `source: 'mobile_app'` to confirm mobile tracking is working.
-
-**Key Events to Look For:**
-
-**🔥 Automatic Events (No Code Required!):**
-- `session_start` - User starts a new session (automatic)
-- `session_end` - User ends session with duration/stats (automatic)
-- `pageviews` - User navigates between screens (automatic)
-- `app_install` - First time app opens with attribution (automatic)
-- `app_update` - App version changes (automatic)
-- `app_foreground` - App becomes active (automatic)
-- `app_background` - App goes to background (automatic)
-- `app_launch_performance` - App startup timing (automatic)
-- `sdk_initialized` - SDK successfully initialized (automatic)
-
-**📱 Manual Events (When You Call Them):**
-- Custom events you track with `datalyr.track()`
-- User identification with `datalyr.identify()`
-- Manual screen views with `datalyr.screen()`
-
-## Debugging
-
-```typescript
-// Check SDK status
-const status = datalyr.getStatus();
-console.log('SDK Status:', status);
-
-// Manually flush events
-await datalyr.flush();
-
-// Enable debug mode
-await datalyr.initialize({
-  workspaceId: 'your-workspace-id',
-  debug: true  // This will show detailed logs
-});
-```
-
-## Common Issues
-
-1. **Events not appearing**: Check debug logs and network connectivity
-2. **Build errors**: Ensure all dependencies are installed and linked
-3. **iOS build issues**: Run `cd ios && pod install`
-4. **Android issues**: Check that your minSdkVersion is >= 21
-
-## Automatic Events
-
-Want to see all the automatic events in action? Check out `auto-events-example.tsx` for a live demo that shows:
-
-- Real-time session tracking with duration and screen counts
-- Automatic screen view detection as you navigate
-- App lifecycle events (foreground/background)
-- Revenue event tracking for purchases
-- Session management and timeout handling
-
-```typescript
-// Get current session info
-const session = datalyr.getCurrentSession();
-console.log('Current session:', session);
-// Output: { sessionId: 'sess_123', startTime: 1640995200000, screenViews: 5, events: 12 }
-
-// Manual revenue tracking (also triggers automatic revenue_event)
-await datalyr.trackRevenue('purchase', {
-  product_id: 'premium_plan',
-  price: 9.99,
-  currency: 'USD',
-});
-
-// Force end session for testing
-await datalyr.endSession();
-```
-
-## Next Steps
-
-- See `example.tsx` for basic integration example
-- See `auto-events-example.tsx` for automatic events demo
-- Check your Datalyr dashboard to verify events are coming through
-- Set up attribution tracking for your ad campaigns
-- Configure conversion events for your key user actions
-
----
-
-## SKAdNetwork Setup (iOS Attribution)
-
-### **1. Add Native Bridge (React Native CLI/Expo Bare)**
-
-Create `ios/YourApp/DatalyrSKAdNetwork.m`:
-```objc
-#import <React/RCTBridgeModule.h>
-#import <StoreKit/StoreKit.h>
-
-@interface DatalyrSKAdNetwork : NSObject <RCTBridgeModule>
-@end
-
-@implementation DatalyrSKAdNetwork
-
-RCT_EXPORT_MODULE();
-
-RCT_EXPORT_METHOD(updateConversionValue:(NSInteger)value
-                  resolve:(RCTPromiseResolveBlock)resolve
-                  reject:(RCTPromiseRejectBlock)reject) {
-    if (@available(iOS 14.0, *)) {
-        @try {
-            [SKAdNetwork updateConversionValue:value];
-            resolve(@(YES));
-        } @catch (NSException *exception) {
-            reject(@"skadnetwork_error", exception.reason, nil);
-        }
-    } else {
-        reject(@"ios_version_error", @"SKAdNetwork requires iOS 14.0+", nil);
-    }
-}
-
-@end
-```
-
-### **2. Track Events with SKAdNetwork**
-
-```typescript
-import { Datalyr } from '@datalyr/react-native-sdk';
-
-// Track events with automatic conversion value encoding
-await Datalyr.trackPurchase(29.99, 'USD', 'premium_plan');
-await Datalyr.trackWithSKAdNetwork('add_to_cart', { product_id: 'shirt_001' });
-await Datalyr.trackWithSKAdNetwork('level_complete', { level: 5, score: 1250 });
-
-// Test conversion values (doesn't send to Apple)
-const value = Datalyr.getConversionValue('purchase', { revenue: 29.99 });
-console.log('Conversion value:', value); // Example: 5
-```
-
-### **3. Industry Templates**
-
-Choose the template that best fits your app:
-
-**E-commerce (`skadTemplate: 'ecommerce'`):**
-- Optimized for: purchase, add_to_cart, begin_checkout, signup, subscribe, view_item
-- Revenue encoding: 8 tiers from $0-1 to $250+
-
-**Gaming (`skadTemplate: 'gaming'`):**
-- Optimized for: level_complete, tutorial_complete, purchase, achievement_unlocked, session_start, ad_watched
-- Revenue encoding for in-app purchases
-
-**Subscription (`skadTemplate: 'subscription'`):**
-- Optimized for: trial_start, subscribe, upgrade, cancel, signup, payment_method_added
-- Revenue encoding for subscription plans
-
----
-
-**Ready to test? Your mobile attribution + automatic events + SKAdNetwork are now live! 🚀**
-
-*Compete with AppsFlyer/Adjust at 90% cost savings while getting Mixpanel-style automatic events!*