@linkforty/mobile-sdk-react-native 1.0.0

package/package.json

@@ -0,0 +1,68 @@
+{
+  "name": "@linkforty/mobile-sdk-react-native",
+  "version": "1.0.0",
+  "description": "React Native SDK for LinkForty - Open-source deep linking and mobile attribution platform",
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "scripts": {
+    "build": "tsc",
+    "prepare": "npm run build",
+    "prepublishOnly": "npm run build",
+    "test": "echo \"Error: no test specified\" && exit 1"
+  },
+  "keywords": [
+    "linkforty",
+    "deep-linking",
+    "deferred-deep-linking",
+    "mobile-attribution",
+    "react-native",
+    "universal-links",
+    "app-links",
+    "app-attribution",
+    "branch-alternative",
+    "appsflyer-alternative",
+    "adjust-alternative",
+    "self-hosted",
+    "open-source",
+    "privacy-focused"
+  ],
+  "author": "LinkForty",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/linkforty/react-native-sdk.git"
+  },
+  "bugs": {
+    "url": "https://github.com/linkforty/react-native-sdk/issues"
+  },
+  "homepage": "https://github.com/linkforty/react-native-sdk#readme",
+  "engines": {
+    "node": ">=20.0.0",
+    "npm": ">=10.0.0"
+  },
+  "peerDependencies": {
+    "react": ">=18.3.0",
+    "react-native": ">=0.76.0"
+  },
+  "dependencies": {
+    "@react-native-async-storage/async-storage": "^2.2.0",
+    "react-native-device-info": "^15.0.0"
+  },
+  "devDependencies": {
+    "@types/react": "^19.1.0",
+    "typescript": "^5.9.0"
+  },
+  "files": [
+    "dist/**/*",
+    "src/**/*",
+    "examples/**/*",
+    "README.md",
+    "CHANGELOG.md",
+    "CONTRIBUTING.md",
+    "LICENSE"
+  ],
+  "publishConfig": {
+    "access": "public",
+    "registry": "https://registry.npmjs.org/"
+  }
+}

package/src/DeepLinkHandler.ts

@@ -0,0 +1,96 @@
+/**
+ * DeepLinkHandler - Handles Universal Links (iOS) and App Links (Android)
+ */
+
+import { Linking } from 'react-native';
+import type { DeepLinkData, DeepLinkCallback } from './types';
+
+export class DeepLinkHandler {
+  private callback: DeepLinkCallback | null = null;
+  private baseUrl: string | null = null;
+
+  /**
+   * Initialize deep link listener
+   */
+  initialize(baseUrl: string, callback: DeepLinkCallback): void {
+    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(): void {
+    Linking.removeAllListeners('url');
+    this.callback = null;
+  }
+
+  /**
+   * Handle incoming deep link
+   */
+  private handleDeepLink = ({ url }: { url: string }): void => {
+    if (!this.callback || !url) {
+      return;
+    }
+
+    const deepLinkData = this.parseURL(url);
+    this.callback(url, deepLinkData);
+  };
+
+  /**
+   * Parse deep link URL and extract data
+   */
+  parseURL(url: string): DeepLinkData | null {
+    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: Record<string, string> = {};
+      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/src/FingerprintCollector.ts

@@ -0,0 +1,90 @@
+/**
+ * FingerprintCollector - Collects device fingerprint data for attribution matching
+ */
+
+import { Platform, Dimensions, NativeModules } from 'react-native';
+import DeviceInfo from 'react-native-device-info';
+import type { DeviceFingerprint } from './types';
+
+export class FingerprintCollector {
+  /**
+   * Collect device fingerprint data
+   */
+  static async collect(): Promise<DeviceFingerprint> {
+    const { width, height } = Dimensions.get('window');
+    const timezone = this.getTimezone();
+    const language = this.getLanguage();
+
+    const fingerprint: DeviceFingerprint = {
+      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(): Promise<string> {
+    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
+   */
+  private static getTimezone(): string {
+    try {
+      // Get timezone using Intl API
+      return Intl.DateTimeFormat().resolvedOptions().timeZone || 'UTC';
+    } catch (error) {
+      return 'UTC';
+    }
+  }
+
+  /**
+   * Get device language
+   */
+  private static getLanguage(): string {
+    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/src/LinkFortySDK.ts

@@ -0,0 +1,320 @@
+/**
+ * LinkFortySDK - Main SDK class for LinkForty deep linking and attribution
+ */
+
+import AsyncStorage from '@react-native-async-storage/async-storage';
+import { FingerprintCollector } from './FingerprintCollector';
+import { DeepLinkHandler } from './DeepLinkHandler';
+import type {
+  LinkFortyConfig,
+  InstallAttributionResponse,
+  DeepLinkData,
+  DeferredDeepLinkCallback,
+  DeepLinkCallback,
+} from './types';
+
+const STORAGE_KEYS = {
+  INSTALL_ID: '@linkforty:install_id',
+  INSTALL_DATA: '@linkforty:install_data',
+  FIRST_LAUNCH: '@linkforty:first_launch',
+};
+
+export class LinkFortySDK {
+  private config: LinkFortyConfig | null = null;
+  private deepLinkHandler: DeepLinkHandler | null = null;
+  private deferredDeepLinkCallback: DeferredDeepLinkCallback | null = null;
+  private installId: string | null = null;
+  private initialized: boolean = false;
+
+  /**
+   * Initialize the SDK
+   */
+  async init(config: LinkFortyConfig): Promise<void> {
+    if (this.initialized) {
+      console.warn('LinkForty SDK already initialized');
+      return;
+    }
+
+    this.config = config;
+
+    if (config.debug) {
+      console.log('[LinkForty] Initializing SDK with config:', config);
+    }
+
+    // Check if this is first launch
+    const isFirstLaunch = await this.isFirstLaunch();
+
+    if (isFirstLaunch) {
+      // Report install and get deferred deep link
+      await this.reportInstall();
+    } else {
+      // Load cached install data
+      await this.loadInstallData();
+    }
+
+    // Initialize deep link handler for direct deep links
+    this.deepLinkHandler = new DeepLinkHandler();
+
+    this.initialized = true;
+
+    if (config.debug) {
+      console.log('[LinkForty] SDK initialized successfully');
+    }
+  }
+
+  /**
+   * Get install attribution data (deferred deep link)
+   */
+  async getInstallData(): Promise<DeepLinkData | null> {
+    const cached = await AsyncStorage.getItem(STORAGE_KEYS.INSTALL_DATA);
+    if (cached) {
+      return JSON.parse(cached);
+    }
+    return null;
+  }
+
+  /**
+   * Register callback for deferred deep links (new installs)
+   */
+  onDeferredDeepLink(callback: DeferredDeepLinkCallback): void {
+    this.deferredDeepLinkCallback = callback;
+
+    // If we already have install data, call the callback immediately
+    this.getInstallData().then((data) => {
+      if (data && this.deferredDeepLinkCallback) {
+        this.deferredDeepLinkCallback(data);
+      }
+    });
+  }
+
+  /**
+   * Register callback for direct deep links (existing users)
+   */
+  onDeepLink(callback: DeepLinkCallback): void {
+    if (!this.config) {
+      throw new Error('SDK not initialized. Call init() first.');
+    }
+
+    if (!this.deepLinkHandler) {
+      this.deepLinkHandler = new DeepLinkHandler();
+    }
+
+    this.deepLinkHandler.initialize(this.config.baseUrl, callback);
+  }
+
+  /**
+   * Track in-app event
+   */
+  async trackEvent(name: string, properties?: Record<string, any>): Promise<void> {
+    if (!this.config) {
+      throw new Error('SDK not initialized. Call init() first.');
+    }
+
+    if (!this.installId) {
+      console.warn('[LinkForty] Cannot track event: No install ID available');
+      return;
+    }
+
+    // Backend expects: { installId, eventName, eventData, timestamp }
+    const requestBody = {
+      installId: this.installId,
+      eventName: name,
+      eventData: properties || {},
+      timestamp: new Date().toISOString(),
+    };
+
+    try {
+      const response = await this.apiRequest('/api/sdk/v1/event', {
+        method: 'POST',
+        body: JSON.stringify(requestBody),
+      });
+
+      if (this.config.debug) {
+        console.log('[LinkForty] Event tracked:', name, response);
+      }
+    } catch (error) {
+      console.error('[LinkForty] Failed to track event:', error);
+    }
+  }
+
+  /**
+   * Get install ID
+   */
+  async getInstallId(): Promise<string | null> {
+    if (this.installId) {
+      return this.installId;
+    }
+
+    const cached = await AsyncStorage.getItem(STORAGE_KEYS.INSTALL_ID);
+    if (cached) {
+      this.installId = cached;
+    }
+
+    return this.installId;
+  }
+
+  /**
+   * Clear all cached data (for testing)
+   */
+  async clearData(): Promise<void> {
+    await AsyncStorage.multiRemove([
+      STORAGE_KEYS.INSTALL_ID,
+      STORAGE_KEYS.INSTALL_DATA,
+      STORAGE_KEYS.FIRST_LAUNCH,
+    ]);
+
+    this.installId = null;
+
+    if (this.config?.debug) {
+      console.log('[LinkForty] All data cleared');
+    }
+  }
+
+  /**
+   * Check if this is the first app launch
+   */
+  private async isFirstLaunch(): Promise<boolean> {
+    const firstLaunchFlag = await AsyncStorage.getItem(STORAGE_KEYS.FIRST_LAUNCH);
+
+    if (!firstLaunchFlag) {
+      await AsyncStorage.setItem(STORAGE_KEYS.FIRST_LAUNCH, 'true');
+      return true;
+    }
+
+    return false;
+  }
+
+  /**
+   * Report app installation to LinkForty backend
+   */
+  private async reportInstall(): Promise<void> {
+    if (!this.config) {
+      return;
+    }
+
+    try {
+      // Collect device fingerprint
+      const fingerprint = await FingerprintCollector.collect();
+
+      if (this.config.debug) {
+        console.log('[LinkForty] Reporting install with fingerprint:', fingerprint);
+      }
+
+      // Parse screen resolution (e.g., "1080x1920" -> [1080, 1920])
+      const [screenWidth, screenHeight] = fingerprint.screenResolution
+        .split('x')
+        .map(Number);
+
+      // Convert attribution window from days to hours
+      const attributionWindowHours = (this.config.attributionWindow || 7) * 24;
+
+      // Call install endpoint with flattened structure matching backend contract
+      const response = await this.apiRequest<InstallAttributionResponse>(
+        '/api/sdk/v1/install',
+        {
+          method: 'POST',
+          body: JSON.stringify({
+            userAgent: fingerprint.userAgent,
+            timezone: fingerprint.timezone,
+            language: fingerprint.language,
+            screenWidth,
+            screenHeight,
+            platform: fingerprint.platform,
+            platformVersion: fingerprint.osVersion,
+            deviceId: undefined, // Optional: Can add IDFA/GAID if available
+            attributionWindowHours,
+          }),
+        }
+      );
+
+      if (this.config.debug) {
+        console.log('[LinkForty] Install response:', response);
+      }
+
+      // Store install ID
+      if (response.installId) {
+        this.installId = response.installId;
+        await AsyncStorage.setItem(STORAGE_KEYS.INSTALL_ID, response.installId);
+      }
+
+      // If attributed, store deep link data
+      if (response.attributed && response.deepLinkData) {
+        await AsyncStorage.setItem(
+          STORAGE_KEYS.INSTALL_DATA,
+          JSON.stringify(response.deepLinkData)
+        );
+
+        // Call deferred deep link callback if registered
+        if (this.deferredDeepLinkCallback) {
+          this.deferredDeepLinkCallback(response.deepLinkData as DeepLinkData);
+        }
+
+        if (this.config.debug) {
+          console.log('[LinkForty] Install attributed with confidence:', response.confidenceScore);
+          console.log('[LinkForty] Matched factors:', response.matchedFactors);
+        }
+      } else {
+        if (this.config.debug) {
+          console.log('[LinkForty] Install not attributed (organic install)');
+        }
+
+        // Call callback with null to indicate organic install
+        if (this.deferredDeepLinkCallback) {
+          this.deferredDeepLinkCallback(null);
+        }
+      }
+    } catch (error) {
+      console.error('[LinkForty] Failed to report install:', error);
+
+      // Call callback with null on error
+      if (this.deferredDeepLinkCallback) {
+        this.deferredDeepLinkCallback(null);
+      }
+    }
+  }
+
+  /**
+   * Load cached install data
+   */
+  private async loadInstallData(): Promise<void> {
+    this.installId = await AsyncStorage.getItem(STORAGE_KEYS.INSTALL_ID);
+  }
+
+  /**
+   * Make API request to LinkForty backend
+   */
+  private async apiRequest<T>(endpoint: string, options: RequestInit = {}): Promise<T> {
+    if (!this.config) {
+      throw new Error('SDK not initialized');
+    }
+
+    const url = `${this.config.baseUrl}${endpoint}`;
+
+    const headers: Record<string, string> = {
+      'Content-Type': 'application/json',
+    };
+
+    // Add API key if provided
+    if (this.config.apiKey) {
+      headers['Authorization'] = `Bearer ${this.config.apiKey}`;
+    }
+
+    const response = await fetch(url, {
+      ...options,
+      headers: {
+        ...headers,
+        ...options.headers,
+      },
+    });
+
+    if (!response.ok) {
+      const error = await response.json().catch(() => ({ message: 'Network error' }));
+      throw new Error(error.message || `HTTP ${response.status}`);
+    }
+
+    return response.json();
+  }
+}
+
+// Export singleton instance
+export default new LinkFortySDK();

package/src/index.ts

@@ -0,0 +1,26 @@
+/**
+ * LinkForty React Native SDK
+ *
+ * Deep linking and mobile attribution for React Native apps
+ *
+ * @packageDocumentation
+ */
+
+// Export singleton SDK instance as default
+export { default } from './LinkFortySDK';
+
+// Export classes
+export { LinkFortySDK } from './LinkFortySDK';
+export { FingerprintCollector } from './FingerprintCollector';
+export { DeepLinkHandler } from './DeepLinkHandler';
+
+// Export types
+export type {
+  LinkFortyConfig,
+  DeviceFingerprint,
+  DeepLinkData,
+  InstallAttributionResponse,
+  EventData,
+  DeferredDeepLinkCallback,
+  DeepLinkCallback,
+} from './types';

package/src/types.ts

@@ -0,0 +1,112 @@
+/**
+ * LinkForty React Native SDK Type Definitions
+ */
+
+/**
+ * Configuration options for initializing the LinkForty SDK
+ */
+export interface LinkFortyConfig {
+  /** Base URL of your LinkForty instance (e.g., 'https://go.yourdomain.com') */
+  baseUrl: string;
+  /** Optional API key for Cloud authentication */
+  apiKey?: string;
+  /** Enable debug logging */
+  debug?: boolean;
+  /** Custom attribution window in days (default: 7) */
+  attributionWindow?: number;
+}
+
+/**
+ * Device fingerprint data collected for attribution matching
+ */
+export interface DeviceFingerprint {
+  /** IP address (server-side) */
+  ip?: string;
+  /** User agent string */
+  userAgent: string;
+  /** Device timezone */
+  timezone: string;
+  /** Device language */
+  language: string;
+  /** Screen resolution (width x height) */
+  screenResolution: string;
+  /** Device platform (ios/android) */
+  platform: string;
+  /** Device model */
+  deviceModel?: string;
+  /** OS version */
+  osVersion?: string;
+  /** App version */
+  appVersion?: string;
+}
+
+/**
+ * Deep link data containing URLs and parameters
+ */
+export interface DeepLinkData {
+  /** Short code that was clicked */
+  shortCode: string;
+  /** iOS app URL */
+  iosUrl?: string;
+  /** Android app URL */
+  androidUrl?: string;
+  /** Web fallback URL */
+  webUrl?: string;
+  /** UTM parameters */
+  utmParameters?: {
+    source?: string;
+    medium?: string;
+    campaign?: string;
+    term?: string;
+    content?: string;
+  };
+  /** Custom query parameters */
+  customParameters?: Record<string, string>;
+  /** Click timestamp */
+  clickedAt?: string;
+  /** Link ID */
+  linkId?: string;
+}
+
+/**
+ * Response from install attribution endpoint
+ * Matches backend contract from /api/sdk/v1/install
+ */
+export interface InstallAttributionResponse {
+  /** Install event UUID */
+  installId: string;
+  /** Whether attribution was successful */
+  attributed: boolean;
+  /** Attribution confidence score (0-100) */
+  confidenceScore: number;
+  /** Array of matched fingerprint factors (e.g., ['ip', 'user_agent', 'timezone', 'language', 'screen']) */
+  matchedFactors: string[];
+  /** Deep link data if attributed (contains shortCode, URLs, UTM params, confidence, etc.) */
+  deepLinkData: DeepLinkData | Record<string, never>;
+}
+
+/**
+ * Event data for tracking in-app events
+ */
+export interface EventData {
+  /** Event name (e.g., 'purchase', 'signup', 'add_to_cart') */
+  name: string;
+  /** Event properties */
+  properties?: Record<string, any>;
+  /** Revenue amount (for conversion events) */
+  revenue?: number;
+  /** Currency code (e.g., 'USD') */
+  currency?: string;
+  /** Install ID for attribution */
+  installId?: string;
+}
+
+/**
+ * Callback function for deferred deep links
+ */
+export type DeferredDeepLinkCallback = (deepLinkData: DeepLinkData | null) => void;
+
+/**
+ * Callback function for direct deep links
+ */
+export type DeepLinkCallback = (url: string, deepLinkData: DeepLinkData | null) => void;