@linkforty/mobile-sdk-react-native 1.0.0

package/README.md

@@ -0,0 +1,410 @@
+# LinkForty React Native SDK
+
+Official React Native SDK for [LinkForty](https://github.com/linkforty/core) - Open-source deep linking and mobile attribution platform.
+
+## Features
+
+- ✅ **Deferred Deep Linking** - Route new users to specific content after install
+- ✅ **Direct Deep Linking** - Handle Universal Links (iOS) and App Links (Android)
+- ✅ **Probabilistic Attribution** - Match installs to clicks with 70%+ confidence
+- ✅ **Event Tracking** - Track in-app events with attribution
+- ✅ **Privacy-Focused** - No persistent device IDs required
+- ✅ **TypeScript Support** - Full type definitions included
+- ✅ **Works with Core & Cloud** - Compatible with self-hosted and Cloud instances
+
+## Installation
+
+```bash
+npm install @linkforty/react-native-sdk
+# or
+yarn add @linkforty/react-native-sdk
+```
+
+### Requirements
+
+- React Native >= 0.76.0
+- React >= 18.3.0
+- Node.js >= 20.0.0
+
+### Additional Dependencies
+
+This SDK requires the following peer dependencies:
+
+```bash
+npm install @react-native-async-storage/async-storage react-native-device-info
+```
+
+### iOS Setup
+
+1. Install CocoaPods dependencies:
+
+```bash
+cd ios && pod install
+```
+
+2. Configure Universal Links in Xcode:
+   - Open your project in Xcode
+   - Select your app target → Signing & Capabilities
+   - Add "Associated Domains" capability
+   - Add domain: `applinks:go.yourdomain.com` (replace with your LinkForty or custom domain)
+
+3. Create AASA file on your server at:
+   ```
+   https://go.yourdomain.com/.well-known/apple-app-site-association
+   ```
+
+   Example AASA file:
+   ```json
+   {
+     "applinks": {
+       "apps": [],
+       "details": [
+         {
+           "appID": "TEAM_ID.com.yourapp.bundle",
+           "paths": ["*"]
+         }
+       ]
+     }
+   }
+   ```
+
+### Android Setup
+
+1. Configure App Links in `android/app/src/main/AndroidManifest.xml`:
+
+```xml
+<activity android:name=".MainActivity">
+  <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>
+</activity>
+```
+
+2. Create Digital Asset Links file on your server at:
+   ```
+   https://go.yourdomain.com/.well-known/assetlinks.json
+   ```
+
+   Example assetlinks.json:
+   ```json
+   [{
+     "relation": ["delegate_permission/common.handle_all_urls"],
+     "target": {
+       "namespace": "android_app",
+       "package_name": "com.yourapp",
+       "sha256_cert_fingerprints": ["YOUR_SHA256_FINGERPRINT"]
+     }
+   }]
+   ```
+
+## Quick Start
+
+```typescript
+import LinkForty from '@linkforty/react-native-sdk';
+
+// Initialize SDK (call in App.tsx or index.js)
+await LinkForty.init({
+  baseUrl: 'https://go.yourdomain.com',
+  apiKey: 'optional-for-cloud-users', // Optional
+  debug: __DEV__, // Enable debug logging in development
+});
+
+// Handle deferred deep links (new installs)
+LinkForty.onDeferredDeepLink((deepLinkData) => {
+  if (deepLinkData) {
+    // User clicked a link before installing
+    console.log('Deferred deep link:', deepLinkData);
+
+    // Navigate to specific content
+    navigation.navigate('Product', {
+      id: deepLinkData.utmParameters?.content
+    });
+  } else {
+    // Organic install (no link clicked)
+    console.log('Organic install');
+  }
+});
+
+// Handle direct deep links (existing users)
+LinkForty.onDeepLink((url, deepLinkData) => {
+  console.log('Deep link opened:', url, deepLinkData);
+
+  if (deepLinkData) {
+    // Navigate to specific content
+    navigation.navigate('Product', {
+      id: deepLinkData.utmParameters?.content
+    });
+  }
+});
+
+// Track in-app events
+await LinkForty.trackEvent('purchase', {
+  amount: 99.99,
+  currency: 'USD',
+  productId: 'premium_plan'
+});
+```
+
+## API Reference
+
+### `init(config: LinkFortyConfig): Promise<void>`
+
+Initialize the SDK. Must be called before using any other methods.
+
+**Parameters:**
+
+- `config.baseUrl` (string, required) - Base URL of your LinkForty instance
+- `config.apiKey` (string, optional) - API key for Cloud authentication
+- `config.debug` (boolean, optional) - Enable debug logging
+- `config.attributionWindow` (number, optional) - Attribution window in days (default: 7)
+
+**Example:**
+
+```typescript
+await LinkForty.init({
+  baseUrl: 'https://go.yourdomain.com',
+  debug: true,
+  attributionWindow: 7,
+});
+```
+
+### `onDeferredDeepLink(callback: (deepLinkData: DeepLinkData | null) => void): void`
+
+Register a callback for deferred deep links. Called when the app is launched for the first time after installation.
+
+**Parameters:**
+
+- `callback` - Function called with deep link data or `null` for organic installs
+
+**Example:**
+
+```typescript
+LinkForty.onDeferredDeepLink((deepLinkData) => {
+  if (deepLinkData) {
+    // Attributed install
+    console.log('User came from:', deepLinkData.utmParameters?.source);
+  } else {
+    // Organic install
+    console.log('Organic install');
+  }
+});
+```
+
+### `onDeepLink(callback: (url: string, deepLinkData: DeepLinkData | null) => void): void`
+
+Register a callback for direct deep links. Called when the app is opened via a Universal Link (iOS) or App Link (Android).
+
+**Parameters:**
+
+- `callback` - Function called with the full URL and parsed deep link data
+
+**Example:**
+
+```typescript
+LinkForty.onDeepLink((url, deepLinkData) => {
+  if (deepLinkData?.shortCode) {
+    // Navigate based on link
+    navigation.navigate('Details', { id: deepLinkData.shortCode });
+  }
+});
+```
+
+### `trackEvent(name: string, properties?: Record<string, any>): Promise<void>`
+
+Track an in-app event with optional properties.
+
+**Parameters:**
+
+- `name` - Event name (e.g., 'purchase', 'signup', 'add_to_cart')
+- `properties` - Optional event properties
+
+**Example:**
+
+```typescript
+await LinkForty.trackEvent('purchase', {
+  amount: 99.99,
+  currency: 'USD',
+  productId: 'premium_plan',
+  category: 'subscription'
+});
+```
+
+### `getInstallData(): Promise<DeepLinkData | null>`
+
+Get cached install attribution data.
+
+**Returns:** Deep link data from install or `null` if not attributed
+
+**Example:**
+
+```typescript
+const installData = await LinkForty.getInstallData();
+if (installData) {
+  console.log('Install source:', installData.utmParameters?.source);
+}
+```
+
+### `getInstallId(): Promise<string | null>`
+
+Get the unique install ID for this app installation.
+
+**Returns:** Install ID or `null` if not available
+
+**Example:**
+
+```typescript
+const installId = await LinkForty.getInstallId();
+console.log('Install ID:', installId);
+```
+
+### `clearData(): Promise<void>`
+
+Clear all cached SDK data. Useful for testing.
+
+**Example:**
+
+```typescript
+await LinkForty.clearData();
+// App will behave as if it's a fresh install
+```
+
+## TypeScript Types
+
+### `DeepLinkData`
+
+```typescript
+interface DeepLinkData {
+  shortCode: string;
+  iosUrl?: string;
+  androidUrl?: string;
+  webUrl?: string;
+  utmParameters?: {
+    source?: string;
+    medium?: string;
+    campaign?: string;
+    term?: string;
+    content?: string;
+  };
+  customParameters?: Record<string, string>;
+  clickedAt?: string;
+  linkId?: string;
+}
+```
+
+### `LinkFortyConfig`
+
+```typescript
+interface LinkFortyConfig {
+  baseUrl: string;
+  apiKey?: string;
+  debug?: boolean;
+  attributionWindow?: number;
+}
+```
+
+## Advanced Usage
+
+### Testing Deferred Deep Linking
+
+1. **Uninstall the app** or clear all data:
+   ```typescript
+   await LinkForty.clearData();
+   ```
+
+2. **Click a LinkForty link** on your device (in Safari/Chrome, not in the app)
+
+3. **Install/Open the app** from App Store/Play Store
+
+4. **Check logs** - you should see attribution data in the `onDeferredDeepLink` callback
+
+### Using with Self-Hosted LinkForty Core
+
+```typescript
+// Point to your self-hosted instance
+await LinkForty.init({
+  baseUrl: 'http://localhost:3000', // or your domain
+  debug: true,
+});
+```
+
+### Using with LinkForty Cloud
+
+```typescript
+// Add API key for Cloud authentication
+await LinkForty.init({
+  baseUrl: 'https://go.yourdomain.com',
+  apiKey: 'your-api-key-here',
+  debug: false,
+});
+```
+
+### Custom Attribution Window
+
+```typescript
+// Change attribution window to 14 days
+await LinkForty.init({
+  baseUrl: 'https://go.yourdomain.com',
+  attributionWindow: 14, // days
+});
+```
+
+## Troubleshooting
+
+### Deep links not working on iOS
+
+1. Verify your AASA file is accessible at `https://go.yourdomain.com/.well-known/apple-app-site-association`
+2. Check that your Team ID and Bundle ID are correct
+3. Make sure "Associated Domains" capability is added in Xcode
+4. Test with a real device (Universal Links don't work in simulator)
+
+### Deep links not working on Android
+
+1. Verify your assetlinks.json file is accessible at `https://go.yourdomain.com/.well-known/assetlinks.json`
+2. Check that your package name and SHA256 fingerprint are correct
+3. Run `adb shell pm get-app-links com.yourapp` to verify link verification status
+4. Make sure `android:autoVerify="true"` is set in your intent filter
+
+### Deferred deep links not attributing
+
+1. Make sure you're testing on first install (or call `clearData()`)
+2. Check debug logs for fingerprint data
+3. Verify your LinkForty backend is receiving the install event
+4. Ensure the click and install happen within the attribution window (default: 7 days)
+5. Try clicking the link and installing from the same network
+
+### TypeScript errors
+
+Make sure you have the latest type definitions installed:
+
+```bash
+npm install --save-dev @types/react @types/react-native
+```
+
+## Contributing
+
+Contributions are welcome! Please see [CONTRIBUTING.md](CONTRIBUTING.md) for guidelines.
+
+## License
+
+MIT License - see [LICENSE](LICENSE) file for details
+
+## Support
+
+- **Documentation:** Coming soon (self-hosting guide available in Core repository)
+- **Issues:** [Report on GitHub](https://github.com/linkforty/react-native-sdk/issues)
+- **Questions:** Open a GitHub Discussion or Issue
+
+## Related Projects
+
+- [LinkForty Cloud](https://linkforty.com) - Cloud platform with dashboard and API
+- [LinkForty Core](https://github.com/linkforty/core) - Self-hosted open-source backend
+- **iOS SDK** - Native Swift SDK (planned for future release)
+- **Android SDK** - Native Kotlin SDK (planned for future release)
+
+---
+
+Made with ❤️ by the LinkForty team

package/dist/DeepLinkHandler.d.ts

@@ -0,0 +1,25 @@
+/**
+ * DeepLinkHandler - Handles Universal Links (iOS) and App Links (Android)
+ */
+import type { DeepLinkData, DeepLinkCallback } from './types';
+export declare class DeepLinkHandler {
+    private callback;
+    private baseUrl;
+    /**
+     * Initialize deep link listener
+     */
+    initialize(baseUrl: string, callback: DeepLinkCallback): void;
+    /**
+     * Clean up listeners
+     */
+    cleanup(): void;
+    /**
+     * Handle incoming deep link
+     */
+    private handleDeepLink;
+    /**
+     * Parse deep link URL and extract data
+     */
+    parseURL(url: string): DeepLinkData | null;
+}
+//# sourceMappingURL=DeepLinkHandler.d.ts.map

package/dist/DeepLinkHandler.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"DeepLinkHandler.d.ts","sourceRoot":"","sources":["../src/DeepLinkHandler.ts"],"names":[],"mappings":"AAAA;;GAEG;AAGH,OAAO,KAAK,EAAE,YAAY,EAAE,gBAAgB,EAAE,MAAM,SAAS,CAAC;AAE9D,qBAAa,eAAe;IAC1B,OAAO,CAAC,QAAQ,CAAiC;IACjD,OAAO,CAAC,OAAO,CAAuB;IAEtC;;OAEG;IACH,UAAU,CAAC,OAAO,EAAE,MAAM,EAAE,QAAQ,EAAE,gBAAgB,GAAG,IAAI;IAe7D;;OAEG;IACH,OAAO,IAAI,IAAI;IAKf;;OAEG;IACH,OAAO,CAAC,cAAc,CAOpB;IAEF;;OAEG;IACH,QAAQ,CAAC,GAAG,EAAE,MAAM,GAAG,YAAY,GAAG,IAAI;CA2C3C"}

package/dist/DeepLinkHandler.js

@@ -0,0 +1,81 @@
+/**
+ * DeepLinkHandler - Handles Universal Links (iOS) and App Links (Android)
+ */
+import { Linking } from 'react-native';
+export class DeepLinkHandler {
+    callback = null;
+    baseUrl = null;
+    /**
+     * Initialize deep link listener
+     */
+    initialize(baseUrl, callback) {
+        this.baseUrl = baseUrl;
+        this.callback = callback;
+        // Listen for deep links when app is already open
+        Linking.addEventListener('url', this.handleDeepLink);
+        // Check if app was opened via deep link
+        Linking.getInitialURL().then((url) => {
+            if (url) {
+                this.handleDeepLink({ url });
+            }
+        });
+    }
+    /**
+     * Clean up listeners
+     */
+    cleanup() {
+        Linking.removeAllListeners('url');
+        this.callback = null;
+    }
+    /**
+     * Handle incoming deep link
+     */
+    handleDeepLink = ({ url }) => {
+        if (!this.callback || !url) {
+            return;
+        }
+        const deepLinkData = this.parseURL(url);
+        this.callback(url, deepLinkData);
+    };
+    /**
+     * Parse deep link URL and extract data
+     */
+    parseURL(url) {
+        try {
+            const parsedUrl = new URL(url);
+            // Check if this is a LinkForty URL
+            if (this.baseUrl && !url.startsWith(this.baseUrl)) {
+                return null;
+            }
+            // Extract short code from path
+            const shortCode = parsedUrl.pathname.replace('/', '');
+            if (!shortCode) {
+                return null;
+            }
+            // Extract UTM parameters
+            const utmParameters = {
+                source: parsedUrl.searchParams.get('utm_source') || undefined,
+                medium: parsedUrl.searchParams.get('utm_medium') || undefined,
+                campaign: parsedUrl.searchParams.get('utm_campaign') || undefined,
+                term: parsedUrl.searchParams.get('utm_term') || undefined,
+                content: parsedUrl.searchParams.get('utm_content') || undefined,
+            };
+            // Extract all other query parameters as custom parameters
+            const customParameters = {};
+            parsedUrl.searchParams.forEach((value, key) => {
+                if (!key.startsWith('utm_')) {
+                    customParameters[key] = value;
+                }
+            });
+            return {
+                shortCode,
+                utmParameters,
+                customParameters: Object.keys(customParameters).length > 0 ? customParameters : undefined,
+            };
+        }
+        catch (error) {
+            console.error('Failed to parse deep link URL:', error);
+            return null;
+        }
+    }
+}

package/dist/FingerprintCollector.d.ts

@@ -0,0 +1,23 @@
+/**
+ * FingerprintCollector - Collects device fingerprint data for attribution matching
+ */
+import type { DeviceFingerprint } from './types';
+export declare class FingerprintCollector {
+    /**
+     * Collect device fingerprint data
+     */
+    static collect(): Promise<DeviceFingerprint>;
+    /**
+     * Generate query parameters from fingerprint for URL
+     */
+    static generateQueryParams(): Promise<string>;
+    /**
+     * Get device timezone
+     */
+    private static getTimezone;
+    /**
+     * Get device language
+     */
+    private static getLanguage;
+}
+//# sourceMappingURL=FingerprintCollector.d.ts.map

package/dist/FingerprintCollector.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"FingerprintCollector.d.ts","sourceRoot":"","sources":["../src/FingerprintCollector.ts"],"names":[],"mappings":"AAAA;;GAEG;AAIH,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,SAAS,CAAC;AAEjD,qBAAa,oBAAoB;IAC/B;;OAEG;WACU,OAAO,IAAI,OAAO,CAAC,iBAAiB,CAAC;IAmBlD;;OAEG;WACU,mBAAmB,IAAI,OAAO,CAAC,MAAM,CAAC;IAiBnD;;OAEG;IACH,OAAO,CAAC,MAAM,CAAC,WAAW;IAS1B;;OAEG;IACH,OAAO,CAAC,MAAM,CAAC,WAAW;CAuB3B"}

package/dist/FingerprintCollector.js

@@ -0,0 +1,79 @@
+/**
+ * FingerprintCollector - Collects device fingerprint data for attribution matching
+ */
+import { Platform, Dimensions, NativeModules } from 'react-native';
+import DeviceInfo from 'react-native-device-info';
+export class FingerprintCollector {
+    /**
+     * Collect device fingerprint data
+     */
+    static async collect() {
+        const { width, height } = Dimensions.get('window');
+        const timezone = this.getTimezone();
+        const language = this.getLanguage();
+        const fingerprint = {
+            userAgent: await DeviceInfo.getUserAgent(),
+            timezone,
+            language,
+            screenResolution: `${width}x${height}`,
+            platform: Platform.OS,
+            deviceModel: await DeviceInfo.getModel(),
+            osVersion: await DeviceInfo.getSystemVersion(),
+            appVersion: await DeviceInfo.getVersion(),
+        };
+        return fingerprint;
+    }
+    /**
+     * Generate query parameters from fingerprint for URL
+     */
+    static async generateQueryParams() {
+        const fingerprint = await this.collect();
+        const params = new URLSearchParams({
+            ua: fingerprint.userAgent,
+            tz: fingerprint.timezone,
+            lang: fingerprint.language,
+            screen: fingerprint.screenResolution,
+            platform: fingerprint.platform,
+            ...(fingerprint.deviceModel && { model: fingerprint.deviceModel }),
+            ...(fingerprint.osVersion && { os: fingerprint.osVersion }),
+            ...(fingerprint.appVersion && { app_version: fingerprint.appVersion }),
+        });
+        return params.toString();
+    }
+    /**
+     * Get device timezone
+     */
+    static getTimezone() {
+        try {
+            // Get timezone using Intl API
+            return Intl.DateTimeFormat().resolvedOptions().timeZone || 'UTC';
+        }
+        catch (error) {
+            return 'UTC';
+        }
+    }
+    /**
+     * Get device language
+     */
+    static getLanguage() {
+        try {
+            // Try to get locale from NativeModules
+            const locale = Platform.select({
+                ios: NativeModules.SettingsManager?.settings?.AppleLocale ||
+                    NativeModules.SettingsManager?.settings?.AppleLanguages?.[0],
+                android: NativeModules.I18nManager?.localeIdentifier,
+            });
+            if (locale) {
+                return locale;
+            }
+            // Fallback to navigator if available
+            if (typeof navigator !== 'undefined' && navigator.language) {
+                return navigator.language;
+            }
+            return 'en-US';
+        }
+        catch (error) {
+            return 'en-US';
+        }
+    }
+}

package/dist/LinkFortySDK.d.ts

@@ -0,0 +1,58 @@
+/**
+ * LinkFortySDK - Main SDK class for LinkForty deep linking and attribution
+ */
+import type { LinkFortyConfig, DeepLinkData, DeferredDeepLinkCallback, DeepLinkCallback } from './types';
+export declare class LinkFortySDK {
+    private config;
+    private deepLinkHandler;
+    private deferredDeepLinkCallback;
+    private installId;
+    private initialized;
+    /**
+     * Initialize the SDK
+     */
+    init(config: LinkFortyConfig): Promise<void>;
+    /**
+     * Get install attribution data (deferred deep link)
+     */
+    getInstallData(): Promise<DeepLinkData | null>;
+    /**
+     * Register callback for deferred deep links (new installs)
+     */
+    onDeferredDeepLink(callback: DeferredDeepLinkCallback): void;
+    /**
+     * Register callback for direct deep links (existing users)
+     */
+    onDeepLink(callback: DeepLinkCallback): void;
+    /**
+     * Track in-app event
+     */
+    trackEvent(name: string, properties?: Record<string, any>): Promise<void>;
+    /**
+     * Get install ID
+     */
+    getInstallId(): Promise<string | null>;
+    /**
+     * Clear all cached data (for testing)
+     */
+    clearData(): Promise<void>;
+    /**
+     * Check if this is the first app launch
+     */
+    private isFirstLaunch;
+    /**
+     * Report app installation to LinkForty backend
+     */
+    private reportInstall;
+    /**
+     * Load cached install data
+     */
+    private loadInstallData;
+    /**
+     * Make API request to LinkForty backend
+     */
+    private apiRequest;
+}
+declare const _default: LinkFortySDK;
+export default _default;
+//# sourceMappingURL=LinkFortySDK.d.ts.map

package/dist/LinkFortySDK.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"LinkFortySDK.d.ts","sourceRoot":"","sources":["../src/LinkFortySDK.ts"],"names":[],"mappings":"AAAA;;GAEG;AAKH,OAAO,KAAK,EACV,eAAe,EAEf,YAAY,EACZ,wBAAwB,EACxB,gBAAgB,EACjB,MAAM,SAAS,CAAC;AAQjB,qBAAa,YAAY;IACvB,OAAO,CAAC,MAAM,CAAgC;IAC9C,OAAO,CAAC,eAAe,CAAgC;IACvD,OAAO,CAAC,wBAAwB,CAAyC;IACzE,OAAO,CAAC,SAAS,CAAuB;IACxC,OAAO,CAAC,WAAW,CAAkB;IAErC;;OAEG;IACG,IAAI,CAAC,MAAM,EAAE,eAAe,GAAG,OAAO,CAAC,IAAI,CAAC;IAiClD;;OAEG;IACG,cAAc,IAAI,OAAO,CAAC,YAAY,GAAG,IAAI,CAAC;IAQpD;;OAEG;IACH,kBAAkB,CAAC,QAAQ,EAAE,wBAAwB,GAAG,IAAI;IAW5D;;OAEG;IACH,UAAU,CAAC,QAAQ,EAAE,gBAAgB,GAAG,IAAI;IAY5C;;OAEG;IACG,UAAU,CAAC,IAAI,EAAE,MAAM,EAAE,UAAU,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,GAAG,OAAO,CAAC,IAAI,CAAC;IAgC/E;;OAEG;IACG,YAAY,IAAI,OAAO,CAAC,MAAM,GAAG,IAAI,CAAC;IAa5C;;OAEG;IACG,SAAS,IAAI,OAAO,CAAC,IAAI,CAAC;IAchC;;OAEG;YACW,aAAa;IAW3B;;OAEG;YACW,aAAa;IAsF3B;;OAEG;YACW,eAAe;IAI7B;;OAEG;YACW,UAAU;CA+BzB;;AAGD,wBAAkC"}