@linkforty/mobile-sdk-react-native 1.0.0

package/examples/BasicSetup.tsx

@@ -0,0 +1,100 @@
+/**
+ * Basic Setup Example
+ *
+ * This example shows the minimal setup required to integrate
+ * LinkForty SDK into a React Native app.
+ */
+
+import React, { useEffect } from 'react';
+import { View, Text, StyleSheet } from 'react-native';
+import LinkForty from '@linkforty/react-native-sdk';
+import { useNavigation } from '@react-navigation/native';
+
+export default function App() {
+  const navigation = useNavigation();
+
+  useEffect(() => {
+    // Initialize SDK on app launch
+    initializeLinkForty();
+  }, []);
+
+  const initializeLinkForty = async () => {
+    try {
+      // Initialize with your LinkForty instance URL
+      await LinkForty.init({
+        baseUrl: 'https://go.yourdomain.com',
+        debug: __DEV__, // Enable debug logging in development
+      });
+
+      console.log('LinkForty SDK initialized successfully');
+
+      // Handle deferred deep links (new installs)
+      LinkForty.onDeferredDeepLink((deepLinkData) => {
+        if (deepLinkData) {
+          console.log('User installed from link:', deepLinkData);
+
+          // Example: Navigate to a specific product
+          if (deepLinkData.customParameters?.productId) {
+            navigation.navigate('Product', {
+              id: deepLinkData.customParameters.productId,
+            });
+          }
+        } else {
+          console.log('Organic install - no attribution');
+        }
+      });
+
+      // Handle direct deep links (existing users)
+      LinkForty.onDeepLink((url, deepLinkData) => {
+        console.log('Deep link opened:', url);
+
+        if (deepLinkData) {
+          // Navigate based on deep link data
+          handleDeepLink(deepLinkData);
+        }
+      });
+    } catch (error) {
+      console.error('Failed to initialize LinkForty:', error);
+    }
+  };
+
+  const handleDeepLink = (deepLinkData) => {
+    // Example: Route to different screens based on UTM parameters
+    const { utmParameters, customParameters } = deepLinkData;
+
+    if (customParameters?.productId) {
+      navigation.navigate('Product', { id: customParameters.productId });
+    } else if (customParameters?.category) {
+      navigation.navigate('Category', { name: customParameters.category });
+    } else if (utmParameters?.campaign === 'summer-sale') {
+      navigation.navigate('Sale');
+    } else {
+      navigation.navigate('Home');
+    }
+  };
+
+  return (
+    <View style={styles.container}>
+      <Text style={styles.title}>LinkForty Example App</Text>
+      <Text style={styles.subtitle}>Check console for deep link logs</Text>
+    </View>
+  );
+}
+
+const styles = StyleSheet.create({
+  container: {
+    flex: 1,
+    justifyContent: 'center',
+    alignItems: 'center',
+    backgroundColor: '#f5f5f5',
+  },
+  title: {
+    fontSize: 24,
+    fontWeight: 'bold',
+    marginBottom: 8,
+  },
+  subtitle: {
+    fontSize: 14,
+    color: '#666',
+  },
+});

package/examples/EcommerceTracking.tsx

@@ -0,0 +1,142 @@
+/**
+ * E-commerce Tracking Example
+ *
+ * This example demonstrates how to track e-commerce events
+ * like product views, add to cart, and purchases.
+ */
+
+import React, { useEffect, useState } from 'react';
+import { View, Text, Button, StyleSheet } from 'react-native';
+import LinkForty from '@linkforty/react-native-sdk';
+
+export default function ProductScreen({ route }) {
+  const { productId } = route.params;
+  const [product, setProduct] = useState(null);
+
+  useEffect(() => {
+    // Track product view
+    trackProductView(productId);
+
+    // Fetch product data
+    fetchProduct(productId);
+  }, [productId]);
+
+  const fetchProduct = async (id: string) => {
+    // Your API call here
+    const productData = {
+      id,
+      name: 'Premium Subscription',
+      price: 99.99,
+      currency: 'USD',
+    };
+    setProduct(productData);
+  };
+
+  const trackProductView = async (id: string) => {
+    try {
+      await LinkForty.trackEvent('product_view', {
+        product_id: id,
+        timestamp: new Date().toISOString(),
+      });
+      console.log('Product view tracked');
+    } catch (error) {
+      console.error('Failed to track product view:', error);
+    }
+  };
+
+  const handleAddToCart = async () => {
+    if (!product) return;
+
+    try {
+      // Track add to cart event
+      await LinkForty.trackEvent('add_to_cart', {
+        product_id: product.id,
+        product_name: product.name,
+        price: product.price,
+        currency: product.currency,
+        quantity: 1,
+      });
+
+      console.log('Add to cart event tracked');
+      // Navigate to cart or show confirmation
+    } catch (error) {
+      console.error('Failed to track add to cart:', error);
+    }
+  };
+
+  const handlePurchase = async () => {
+    if (!product) return;
+
+    try {
+      // Process payment with your payment processor
+      const orderId = await processPayment(product);
+
+      // Track purchase event (conversion event)
+      await LinkForty.trackEvent('purchase', {
+        order_id: orderId,
+        product_id: product.id,
+        product_name: product.name,
+        amount: product.price,
+        currency: product.currency,
+        quantity: 1,
+        payment_method: 'credit_card',
+        timestamp: new Date().toISOString(),
+      });
+
+      console.log('Purchase event tracked - this triggers webhooks!');
+
+      // Show success message and navigate
+      alert('Purchase successful!');
+    } catch (error) {
+      console.error('Purchase failed:', error);
+    }
+  };
+
+  const processPayment = async (product) => {
+    // Your payment processing logic
+    return 'ORDER-' + Date.now();
+  };
+
+  if (!product) {
+    return (
+      <View style={styles.container}>
+        <Text>Loading...</Text>
+      </View>
+    );
+  }
+
+  return (
+    <View style={styles.container}>
+      <Text style={styles.title}>{product.name}</Text>
+      <Text style={styles.price}>
+        ${product.price} {product.currency}
+      </Text>
+
+      <View style={styles.buttonContainer}>
+        <Button title="Add to Cart" onPress={handleAddToCart} />
+        <Button title="Buy Now" onPress={handlePurchase} />
+      </View>
+    </View>
+  );
+}
+
+const styles = StyleSheet.create({
+  container: {
+    flex: 1,
+    padding: 20,
+    backgroundColor: '#fff',
+  },
+  title: {
+    fontSize: 24,
+    fontWeight: 'bold',
+    marginBottom: 10,
+  },
+  price: {
+    fontSize: 20,
+    color: '#26adae',
+    marginBottom: 20,
+  },
+  buttonContainer: {
+    gap: 10,
+  },
+});

package/examples/README.md

@@ -0,0 +1,318 @@
+# LinkForty React Native SDK Examples
+
+This directory contains practical examples demonstrating how to integrate and use the LinkForty React Native SDK in real-world applications.
+
+## Examples
+
+### 1. BasicSetup.tsx
+**Level:** Beginner
+**Use Case:** Getting started with LinkForty
+
+Shows the minimal setup required to integrate LinkForty into a React Native app:
+- SDK initialization
+- Handling deferred deep links (new installs)
+- Handling direct deep links (existing users)
+- Basic navigation based on deep link data
+
+**Key Concepts:**
+- SDK configuration
+- Deep link callbacks
+- UTM parameter routing
+
+---
+
+### 2. EcommerceTracking.tsx
+**Level:** Intermediate
+**Use Case:** E-commerce and conversion tracking
+
+Demonstrates tracking e-commerce events for attribution and analytics:
+- Product view tracking
+- Add to cart events
+- Purchase conversion tracking
+- Revenue and order tracking
+
+**Key Concepts:**
+- Event tracking API
+- Conversion events
+- Webhook triggers
+- Revenue attribution
+
+**Triggers Webhooks:** ✅ Yes (on purchase events)
+
+---
+
+### 3. SelfHostedSetup.tsx
+**Level:** Intermediate
+**Use Case:** Using self-hosted LinkForty Core
+
+Shows how to configure the SDK for self-hosted LinkForty Core instances:
+- Local development setup
+- Production self-hosted setup
+- Custom attribution windows
+- Docker Compose configuration
+
+**Key Concepts:**
+- Self-hosting configuration
+- Custom base URLs
+- Development vs. production setups
+- Docker deployment
+
+---
+
+### 4. AdvancedHooks.tsx
+**Level:** Advanced
+**Use Case:** TypeScript and custom React hooks
+
+Advanced patterns using custom React hooks and TypeScript:
+- `useLinkForty` - SDK initialization hook
+- `useInstallAttribution` - Attribution data hook
+- `useDeepLink` - Deep link handling hook
+- `useEventTracking` - Event tracking with state management
+- TypeScript utility functions
+- Error handling patterns
+
+**Key Concepts:**
+- Custom React hooks
+- TypeScript patterns
+- State management
+- Error handling
+- Utility functions
+
+---
+
+## Quick Start
+
+### Running the Examples
+
+1. **Create a new React Native project:**
+   ```bash
+   npx react-native init LinkFortyExample
+   cd LinkFortyExample
+   ```
+
+2. **Install the SDK:**
+   ```bash
+   npm install @linkforty/react-native-sdk
+   npm install @react-native-async-storage/async-storage react-native-device-info
+   ```
+
+3. **Copy an example:**
+   ```bash
+   # Copy the example you want to try
+   cp node_modules/@linkforty/react-native-sdk/examples/BasicSetup.tsx ./App.tsx
+   ```
+
+4. **Update configuration:**
+   ```typescript
+   // Replace with your LinkForty instance URL
+   await LinkForty.init({
+     baseUrl: 'https://go.yourdomain.com',
+     debug: true,
+   });
+   ```
+
+5. **Configure deep linking:**
+
+   **iOS (ios/YourApp/Info.plist):**
+   ```xml
+   <key>CFBundleURLTypes</key>
+   <array>
+     <dict>
+       <key>CFBundleURLSchemes</key>
+       <array>
+         <string>yourapp</string>
+       </array>
+     </dict>
+   </array>
+   ```
+
+   **Android (android/app/src/main/AndroidManifest.xml):**
+   ```xml
+   <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="https" />
+     <data android:host="go.yourdomain.com" />
+   </intent-filter>
+   ```
+
+6. **Run the app:**
+   ```bash
+   # iOS
+   npx react-native run-ios
+
+   # Android
+   npx react-native run-android
+   ```
+
+---
+
+## Testing Deep Links
+
+### iOS Testing
+
+1. **Create a test link** in your LinkForty dashboard
+2. **Uninstall the app** from your device
+3. **Open Safari** and navigate to your LinkForty short link
+4. **Install the app** from the App Store or Xcode
+5. **Check the console** for deferred deep link data
+
+### Android Testing
+
+1. **Create a test link** in your LinkForty dashboard
+2. **Uninstall the app** from your device
+3. **Open Chrome** and navigate to your LinkForty short link
+4. **Install the app** from the Play Store or Android Studio
+5. **Check Logcat** for deferred deep link data
+
+### Testing Direct Deep Links (Existing Users)
+
+```bash
+# iOS
+xcrun simctl openurl booted "https://go.yourdomain.com/abc123"
+
+# Android
+adb shell am start -W -a android.intent.action.VIEW \
+  -d "https://go.yourdomain.com/abc123" com.yourapp
+```
+
+---
+
+## Common Use Cases
+
+### E-commerce App
+Use `EcommerceTracking.tsx` to:
+- Track product views for analytics
+- Monitor add-to-cart conversion rates
+- Attribute purchases to marketing campaigns
+- Trigger conversion webhooks to your backend
+
+### Content App
+Use `BasicSetup.tsx` to:
+- Route users to specific articles or videos
+- Track content engagement
+- Measure campaign effectiveness
+- Enable social sharing with attribution
+
+### SaaS/Subscription App
+Combine `EcommerceTracking.tsx` + `AdvancedHooks.tsx` to:
+- Track trial signups
+- Monitor subscription conversions
+- Attribute revenue to campaigns
+- Calculate customer acquisition cost (CAC)
+
+---
+
+## 🔗 Deep Link URL Structure
+
+### Example LinkForty Link
+```
+https://go.yourdomain.com/summer24
+```
+
+### Configured URLs in LinkForty Dashboard
+
+**iOS URL:**
+```
+yourapp://product/123?ref=summer24
+```
+
+**Android URL:**
+```
+yourapp://product/123?ref=summer24
+```
+
+**UTM Parameters:**
+```
+utm_source=facebook
+utm_medium=cpc
+utm_campaign=summer-sale
+utm_content=product-123
+```
+
+### Handling in Your App
+
+```typescript
+LinkForty.onDeepLink((url, deepLinkData) => {
+  console.log('Full URL:', url);
+  // Output: yourapp://product/123?ref=summer24
+
+  console.log('Deep link data:', deepLinkData);
+  // Output: {
+  //   shortCode: 'summer24',
+  //   utmParameters: {
+  //     source: 'facebook',
+  //     medium: 'cpc',
+  //     campaign: 'summer-sale',
+  //     content: 'product-123'
+  //   },
+  //   customParameters: {
+  //     ref: 'summer24'
+  //   }
+  // }
+
+  // Navigate to product screen
+  navigation.navigate('Product', { id: '123' });
+});
+```
+
+---
+
+## Debugging Tips
+
+### Enable Debug Logging
+
+```typescript
+await LinkForty.init({
+  baseUrl: 'https://go.yourdomain.com',
+  debug: true, // Enable verbose logging
+});
+```
+
+### Check Install Data
+
+```typescript
+const installData = await LinkForty.getInstallData();
+console.log('Install data:', installData);
+```
+
+### Clear Cached Data (Testing)
+
+```typescript
+await LinkForty.clearData();
+// App will behave as if it's a fresh install
+```
+
+### Verify SDK Health
+
+```bash
+# Check if your LinkForty instance is reachable
+curl https://go.yourdomain.com/api/sdk/v1/health
+```
+
+---
+
+## Additional Resources
+
+- **Full Documentation:** [https://docs.linkforty.com](https://docs.linkforty.com)
+- **API Reference:** See main [README.md](../README.md#api-reference)
+- **GitHub Issues:** [Report bugs or request features](https://github.com/linkforty/react-native-sdk/issues)
+
+---
+
+## Contributing
+
+Have a great example to share? We'd love to include it!
+
+1. Create your example following the existing pattern
+2. Add documentation to this README
+3. Submit a pull request
+
+See [CONTRIBUTING.md](../CONTRIBUTING.md) for guidelines.
+
+---
+
+## License
+
+All examples are licensed under the MIT License - use them freely in your projects!

package/examples/SelfHostedSetup.tsx

@@ -0,0 +1,126 @@
+/**
+ * Self-Hosted LinkForty Core Setup Example
+ *
+ * This example shows how to use the SDK with a self-hosted
+ * LinkForty Core instance.
+ */
+
+import React, { useEffect } from 'react';
+import LinkForty from '@linkforty/react-native-sdk';
+
+export default function App() {
+  useEffect(() => {
+    initializeSelfHosted();
+  }, []);
+
+  const initializeSelfHosted = async () => {
+    try {
+      // Option 1: Local Development
+      await LinkForty.init({
+        baseUrl: 'http://192.168.1.100:3000', // Your local machine IP
+        debug: true,
+        attributionWindow: 7, // 7 days
+      });
+
+      // Option 2: Self-Hosted Production
+      // await LinkForty.init({
+      //   baseUrl: 'https://links.yourcompany.com',
+      //   debug: false,
+      //   attributionWindow: 14, // 14 days
+      // });
+
+      // Option 3: Self-Hosted with Custom Domain
+      // await LinkForty.init({
+      //   baseUrl: 'https://go.yourapp.com',
+      //   debug: false,
+      // });
+
+      console.log('Connected to self-hosted LinkForty instance');
+
+      // Set up deep link handlers
+      setupDeepLinkHandlers();
+    } catch (error) {
+      console.error('Failed to connect to self-hosted instance:', error);
+    }
+  };
+
+  const setupDeepLinkHandlers = () => {
+    LinkForty.onDeferredDeepLink((deepLinkData) => {
+      if (deepLinkData) {
+        console.log('Attribution data:', {
+          source: deepLinkData.utmParameters?.source,
+          medium: deepLinkData.utmParameters?.medium,
+          campaign: deepLinkData.utmParameters?.campaign,
+        });
+
+        // Track install with custom properties
+        trackCustomInstall(deepLinkData);
+      }
+    });
+
+    LinkForty.onDeepLink((url, deepLinkData) => {
+      console.log('Deep link URL:', url);
+      console.log('Deep link data:', deepLinkData);
+    });
+  };
+
+  const trackCustomInstall = async (deepLinkData) => {
+    try {
+      // Track install event with custom attribution data
+      await LinkForty.trackEvent('app_install', {
+        source: deepLinkData.utmParameters?.source || 'organic',
+        medium: deepLinkData.utmParameters?.medium || 'none',
+        campaign: deepLinkData.utmParameters?.campaign || 'none',
+        click_id: deepLinkData.linkId,
+        timestamp: new Date().toISOString(),
+      });
+
+      console.log('Install tracked on self-hosted instance');
+    } catch (error) {
+      console.error('Failed to track install:', error);
+    }
+  };
+
+  return null; // Your app UI
+}
+
+/**
+ * Docker Compose Setup for Self-Hosting
+ *
+ * To run LinkForty Core locally with Docker:
+ *
+ * 1. Create docker-compose.yml:
+ *
+ * ```yaml
+ * version: '3.8'
+ * services:
+ *   linkforty:
+ *     image: linkforty/linkforty:latest
+ *     ports:
+ *       - "3000:3000"
+ *     environment:
+ *       DATABASE_URL: postgresql://postgres:password@postgres:5432/linkforty
+ *       REDIS_URL: redis://redis:6379
+ *   postgres:
+ *     image: postgres:15-alpine
+ *     environment:
+ *       POSTGRES_DB: linkforty
+ *       POSTGRES_PASSWORD: password
+ *   redis:
+ *     image: redis:7-alpine
+ * ```
+ *
+ * 2. Start services:
+ * ```bash
+ * docker-compose up -d
+ * ```
+ *
+ * 3. Access at http://localhost:3000
+ *
+ * 4. Update SDK to point to your local IP:
+ * ```typescript
+ * await LinkForty.init({
+ *   baseUrl: 'http://192.168.1.100:3000'
+ * });
+ * ```
+ */