ChottuLink React Native SDK

ChottuLink offers a powerful, scalable deep linking solution, seamlessly replacing Firebase. Integrate effortlessly with your marketing stack to optimize performance and gain insights, all with minimal disruption.

This React Native SDK is built with Nitro Modules for maximum performance and type safety.

✨ Features

• �� High Performance: Built with Nitro Modules for near-native performance
• 🔗 Dynamic Link Creation: Create short, trackable links with UTM parameters
• 📱 Cross-Platform: Full support for iOS and Android
• 🎯 Deep Link Handling
• 📊 Analytics: Built-in tracking and analytics
• 🛡️ Type Safe: Full TypeScript support with generated type definitions
• ⚡ Modern: Uses Swift async/await and Kotlin coroutines

📦 Installation

npm install chottulink-rn-sdk react-native-nitro-modules

Note: react-native-nitro-modules is required as this library relies on Nitro Modules.

🔧 Platform Configuration

iOS Configuration

To enable deep link handling on iOS, you need to add the following methods to your AppDelegate.swift:

import UIKit
import React

@UIApplicationMain
class AppDelegate: UIResponder, UIApplicationDelegate {
  // ... existing code ...

  // Add these methods for deep link handling
  func application(_ app: UIApplication, open url: URL, options: [UIApplication.OpenURLOptionsKey : Any] = [:]) -> Bool {
    return RCTLinkingManager.application(app, open: url, options: options)
  }

  func application(_ application: UIApplication, continue userActivity: NSUserActivity, restorationHandler: @escaping ([any UIUserActivityRestoring]?) -> Void) -> Bool {
    return RCTLinkingManager.application(application, continue: userActivity, restorationHandler: restorationHandler)
  }
}

🚀 Quick Start

1. Initialize the SDK

import { initializeChottuLink } from 'chottulink-rn-sdk';

// Initialize with your API key
initializeChottuLink('your-api-key-here');

2. Set up Event Listeners

import {
  onInitializationSuccess,
  onDeepLinkResolved,
  onDeepLinkFailed,
} from 'chottulink-rn-sdk';

// Listen for initialization success
onInitializationSuccess((event) => {
  console.log('SDK initialized successfully:', event.apiKey);
});

// Listen for deep link resolution
onDeepLinkResolved((event) => {
  console.log('Deep link resolved:', event.url);
  console.log('Metadata:', event.metadata);
});

// Listen for deep link failures
onDeepLinkFailed((event) => {
  console.log('Deep link failed:', event.error);
  console.log('Error code:', event.errorCode);
});

3. Create Dynamic Links

import { createDynamicLink, type RnCLDynamicLink } from 'chottulink-rn-sdk';

const linkData: RnCLDynamicLink = {
  destinationURL: 'https://your-app.com/screen',
  domain: 'your-domain.chottu.link',
  linkName: 'welcome-campaign',
  socialTitle: 'Check out our app!',
  socialDescription: 'Amazing features await you',
  socialImageUrl: 'https://your-domain.com/image.png',
  utmSource: 'email',
  utmMedium: 'campaign',
  utmCampaign: 'welcome',
  utmContent: 'banner',
  utmTerm: 'react-native',
};

try {
  const shortUrl = await createDynamicLink(linkData);
  console.log('Created dynamic link:', shortUrl);
} catch (error) {
  console.error('Failed to create link:', error);
}

4. Handle Incoming Links

import { handleLink } from 'chottulink-rn-sdk';
import { Linking } from 'react-native';

// Handle cold start (app opened from link)
useEffect(() => {
  const handleInitialURL = async () => {
    const initialUrl = await Linking.getInitialURL();
    if (initialUrl) {
      handleLink(initialUrl);
    }
  };

  handleInitialURL();
}, []);

// Handle foreground links
useEffect(() => {
  const subscription = Linking.addEventListener('url', (event) => {
    handleLink(event.url);
  });

  return () => subscription?.remove();
}, []);

5. (Optional) Resolve Link Data from URLs

import { getAppLinkDataFromUrl } from 'chottulink-rn-sdk';

// Resolve link data from a ChottuLink URL
try {
  const resolvedData = await getAppLinkDataFromUrl('https://your-domain.chottu.link/abc123');
  console.log('Original link:', resolvedData.link);
  console.log('Short link:', resolvedData.shortLink);
} catch (error) {
  console.error('Failed to resolve link data:', error);
}

Types

RnCLDynamicLink

Configuration object for creating dynamic links.

interface RnCLDynamicLink {
  destinationURL: string;           // Required: The final destination URL
  domain: string;                   // Required: Your ChottuLink domain
  androidBehaviour?: RnCLDynamicLinkAndroidBehaviour;  // Optional: Android behavior
  iosBehaviour?: RnCLDynamicLinkAndroidBehaviour;      // Optional: iOS behavior
  linkName?: string;                // Optional: Custom link name
  selectedPath?: string;            // Optional: Custom path
  socialTitle?: string;             // Optional: Social sharing title
  socialDescription?: string;       // Optional: Social sharing description
  socialImageUrl?: string;          // Optional: Social sharing image
  utmSource?: string;               // Optional: UTM source parameter
  utmMedium?: string;               // Optional: UTM medium parameter
  utmCampaign?: string;             // Optional: UTM campaign parameter
  utmContent?: string;              // Optional: UTM content parameter
  utmTerm?: string;                 // Optional: UTM term parameter
}

RnCLDynamicLinkAndroidBehaviour

Enum for platform-specific link behavior.

enum RnCLDynamicLinkAndroidBehaviour {
  browser = 1,  // Open in browser
  app = 2,      // Open in app
}

RnCLResolvedLink

Interface for resolved link data from URLs.

interface RnCLResolvedLink {
  link?: string;        // Optional: The original destination URL
  shortLink?: string;   // Optional: The short ChottuLink URL
}

Event Types

interface InitSuccessEvent {
  apiKey: string;
}

interface DeepLinkResolvedEvent {
  url: string;
  metadata: Record<string, string>;
}

interface DeepLinkFailedEvent {
  originalUrl?: string;
  error: string;
  errorCode: number;
}

⚙️ Configuration

Platform-Specific Behavior

You can control how links behave on different platforms:

const linkData: RnCLDynamicLink = {
  destinationURL: 'https://your-app.com/screen',
  domain: 'your-domain.chottu.link',
  androidBehaviour: RnCLDynamicLinkAndroidBehaviour.app,  // Open in app on Android
  iosBehaviour: RnCLDynamicLinkAndroidBehaviour.browser,  // Open in browser on iOS
};

UTM Tracking

Track your marketing campaigns with UTM parameters:

const linkData: RnCLDynamicLink = {
  destinationURL: 'https://your-app.com/screen',
  domain: 'your-domain.chottu.link',
  utmSource: 'email',
  utmMedium: 'newsletter',
  utmCampaign: 'summer-sale',
  utmContent: 'banner-1',
  utmTerm: 'discount',
};

Social Sharing

Customize how your links appear when shared:

const linkData: RnCLDynamicLink = {
  destinationURL: 'https://your-app.com/screen',
  domain: 'your-domain.chottu.link',
  socialTitle: 'Amazing App Features',
  socialDescription: 'Discover what makes our app special',
  socialImageUrl: 'https://your-domain.com/share-image.png',
};

🏗️ Advanced Usage

Complete Example

import React, { useEffect } from 'react';
import { Linking } from 'react-native';
import {
  initializeChottuLink,
  createDynamicLink,
  handleLink,
  onInitializationSuccess,
  onDeepLinkResolved,
  onDeepLinkFailed,
  type RnCLDynamicLink,
} from 'chottulink-rn-sdk';

const App = () => {
  useEffect(() => {
    // Initialize SDK
    initializeChottuLink('your-api-key-here');

    // Set up event listeners
    onInitializationSuccess((event) => {
      console.log('SDK initialized:', event.apiKey);
    });

    onDeepLinkResolved((event) => {
      console.log('Deep link resolved:', event.url);
      // Navigate to the appropriate screen based on the URL
      navigateToScreen(event.url);
    });

    onDeepLinkFailed((event) => {
      console.log('Deep link failed:', event.error);
      // Handle the error appropriately
    });

    // Handle cold start
    const handleInitialURL = async () => {
      const initialUrl = await Linking.getInitialURL();
      if (initialUrl) {
        handleLink(initialUrl);
      }
    };
    handleInitialURL();

    // Handle foreground links
    const subscription = Linking.addEventListener('url', (event) => {
      handleLink(event.url);
    });

    return () => subscription?.remove();
  }, []);

  const createCampaignLink = async () => {
    const linkData: RnCLDynamicLink = {
      destinationURL: 'https://your-app.com/campaign',
      domain: 'your-domain.chottu.link',
      linkName: 'summer-campaign',
      socialTitle: 'Summer Sale!',
      socialDescription: 'Get 50% off on all items',
      socialImageUrl: 'https://your-domain.com/summer-sale.png',
      utmSource: 'app',
      utmMedium: 'push',
      utmCampaign: 'summer-sale-2024',
    };

    try {
      const shortUrl = await createDynamicLink(linkData);
      console.log('Campaign link created:', shortUrl);
      return shortUrl;
    } catch (error) {
      console.error('Failed to create campaign link:', error);
      throw error;
    }
  };

  const resolveLinkData = async (url: string) => {
    try {
      const resolvedData = await getAppLinkDataFromUrl(url);
      console.log('Resolved link data:', resolvedData);
      return resolvedData;
    } catch (error) {
      console.error('Failed to resolve link data:', error);
      throw error;
    }
  };

  return (
    // Your app components
  );
};

🚀 Performance

This SDK is built with Nitro Modules for maximum performance:

• Near-native performance with JSI (JavaScript Interface)
• Zero bridge overhead for native method calls
• Efficient memory management with proper garbage collection
• Type-safe with compile-time type checking

🔗 Links

• ChottuLink Website
• Nitro Modules Documentation
• React Native Documentation

📞 Support

If you encounter any issues or have questions, please:

• Check our documentation