AppsOnAir-react-native-AppLink

AppsOnAir-react-native-AppLink enables seamless handling of deep links and in-app routing within your React Native app. With simple integration, you can configure, manage, and act on links directly from the web dashboard in real time. For more details, refer to the documentation.

🚀 Features

• ✅ Deep link support (URI schemes and AppLinks)
• ✅ Fallback behavior (e.g., open Play Store or App Store)
• ✅ Custom domain support
• ✅ Seamless migration from Firebase Dynamic Links to AppLink

Note: For comprehensive instructions on migrating Firebase Dynamic Links to AppLinks, refer to the documentation.

Installation

Install the AppsOnAir React Native AppLink package using npm:

npm install appsonair-react-native-applink

After installation, navigate to your iOS project directory and install the native dependencies using CocoaPods:

cd ios
pod install
cd ..

Minimum Requirements

Android

• Android Gradle Plugin (AGP): version 8.0.2 or higher
• Kotlin: version 1.7.10 or higher
• Gradle: version 8.0 or higher

iOS

• Minimum deployment target: iOS 13.0

Android Setup

Adding AppId in AndroidManifest.xml

Add the following <meta-data> tag to your application’s AndroidManifest.xml file inside the <application> tag:

• Make sure the android:name is set to "AppsonairAppId"
• Replace the android:value with your actual AppId provided by AppsOnAir

</application>
    ...
    <meta-data
        android:name="AppsonairAppId"
        android:value="********-****-****-****-************" />
</application>

Adding Intent-Filter in AndroidManifest.xml

Add the following <intent-filter> inside the <activity> tag of your main activity in AndroidManifest.xml:

• Replace your-domain.com with your actual domain configured in AppsOnAir.

 <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:host="your-domain.com"
     android:scheme="https" />
 </intent-filter>

If you're using a custom URI scheme, add this additional <intent-filter> block under the same activity:

• Replace your-domain.com and your-scheme with the custom domain and scheme you’ve defined.

 <intent-filter>
    <action android:name="android.intent.action.VIEW" />
    <category android:name="android.intent.category.DEFAULT" />
    <category android:name="android.intent.category.BROWSABLE" />
    <data
     android:host="your-domain.com"
     android:scheme="your-scheme" />
</intent-filter>

Update your MainActivity.kt to handle incoming deep links by overriding the onNewIntent method.

Handling Deep Links in MainActivity

Update your MainActivity.kt to handle incoming deep links by overriding the onNewIntent method.

Make sure the following imports are present at the top of your MainActivity.kt:

import android.content.Intent
import com.appsonairreactnativeapplink.AppsonairReactNativeApplinkModule
import com.facebook.react.ReactApplication

In your MainActivity.kt class (which should extend ReactActivity), override the onNewIntent method as shown below:

class MainActivity : ReactActivity() {
    ...
    ...
    override fun onNewIntent(intent: Intent) {
    super.onNewIntent(intent)
    setIntent(intent)

        val reactContext = (application as? ReactApplication)
            ?.reactNativeHost
            ?.reactInstanceManager
            ?.currentReactContext

        if (reactContext != null) {
            reactContext
            .getNativeModule(AppsonairReactNativeApplinkModule::class.java)
            ?.onNewIntent(intent)
        }
    }
}

iOS Setup

Adding AppId in Info.plist

• Replace the <string> value with your actual AppsOnAir AppId

<key>AppsonairAppId</key>
<string>XXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX</string>

Universal Links (Associated Domains)

To support Universal Links, create or edit the YOUR_PROJECT.entitlements file and add the following configuration:

<!-- If Using Universal Links -->
<key>com.apple.developer.associated-domains</key>
<array>
    <string>applinks:YOUR_DOMAIN</string> <!-- Replace with your actual domain -->
</array>

Note: After configuring the Associated Domain for Universal Links, it may take up to 24 hours for the changes to propagate and become active. The setup and verification process is handled by Apple.

To support a Custom URL Scheme, add the following to your app’s Info.plist file:

<!-- If Using Custom Url Schema -->
<key>CFBundleURLTypes</key>
<array>
    <dict>
        <key>CFBundleURLName</key>
        <string>YOUR_URL_NAME</string>
        <key>CFBundleURLSchemes</key>
        <array>
          <string>YOUR_CUSTOM_URL_SCHEME</string> <!-- Replace with your custom URL scheme -->
        </array>
    </dict>
</array>

Replace YOUR_URL_NAME with a descriptive name for your app, and YOUR_CUSTOM_URL_SCHEME with the scheme you want to use.

iOS Deep Link Handling in AppDelegate.swift

To handle both Universal Links and Custom URL Schemes, add the following methods to your AppDelegate.swift file:

// Step 1: Import AppsOnAir_AppLink
import AppsOnAir_AppLink
...

// Step 2: AppLink Class instance create
var window: UIWindow?
let appLinkService = AppLinkService.shared
...

    // Step 3: Handle AppLink Service
    func application(_ application: UIApplication, continue userActivity: NSUserActivity, restorationHandler: @escaping ([UIUserActivityRestoring]?) -> Void) -> Bool {
        guard userActivity.activityType == NSUserActivityTypeBrowsingWeb,
        let url = userActivity.webpageURL else {
            return false
        }
        appLinkService.handleAppLink(incomingURL: url)
        return true
    }

    func application(_ app: UIApplication, open url: URL, options: [UIApplication.OpenURLOptionsKey : Any] = [:]) -> Bool {
        appLinkService.handleAppLink(incomingURL: url)
        return true
    }

Usage

Function 1: Initialize AppLink

Before handling any deep links, you need to initialize the AppsOnAir AppLink SDK. This is typically done in your app’s entry point — such as inside a top-level component or during app startup.

import React, { useEffect } from 'react';
import { initializeAppLink } from 'appsonair-react-native-applink';

const App = () => {
  useEffect(() => {
    // Initialize AppLink on app startup
    initializeAppLink();
  }, []);

  return (
    // your JSX
  );
};

Function 2: Listen for Deep Link Events

Use onDeepLinkProcessed to listen for incoming deep links after initialization. This allows you to respond to navigation events or extract data from the link.

import React, { useEffect } from 'react';
import {
  initializeAppLink,
  onDeepLinkProcessed,
} from 'appsonair-react-native-applink';

const App = () => {
  useEffect(() => {
    initializeAppLink();

    // Subscribe to deep link events
    const sub = onDeepLinkProcessed(event => {
      console.log(`✅ Processed:\n${JSON.stringify(event, null, 2)}`);
    });

    // Cleanup on unmount
    return () => {
      sub?.remove();
    };
  }, []);

  return (
    // your UI rendering deepLinkResult
  );
};

Function 3: Listen for Referral Events

Use onReferralLinkDetected to listen for referral detected after initialization. This allows you to respond to navigation events or extract data from the link.

import React, { useEffect } from 'react';
import {
  initializeAppLink,
  onReferralLinkDetected
} from 'appsonair-react-native-applink';

const App = () => {
  useEffect(() => {
    initializeAppLink();

    const sub = onReferralLinkDetected((event) => {
      console.log(`✅ Referral:\n${JSON.stringify(event, null, 2)}`);
    });

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

  return (
    // your UI rendering deepLinkResult
  );
};

Function 4: Create a New AppLink

Use createAppLink to programmatically generate a New AppLink from your React Native app by passing a structured set of parameters.

import React, { useState } from 'react';
import { Alert, Button, TextInput, View } from 'react-native';
import {
  createAppLink,
  type AppLinkParams,
  type CreateAppLinkResponse,
} from 'appsonair-react-native-applink';

const App = () => {
  const [linkParams, setLinkParams] = useState<AppLinkParams>({
    name: '',
    url: '',
    urlPrefix: '', // Replace with your actual domain prefix
    iosFallbackUrl: '',
    androidFallbackUrl: '',
    shortId: '',
    isOpenInAndroidApp: true,
    isOpenInBrowserAndroid: false,
    isOpenInIosApp: true,
    isOpenInBrowserApple: false,
  });

  const handleCreateLink = async () => {
    try {
      const result: CreateAppLinkResponse = await createAppLink(linkParams);

      if ('error' in result) {
        throw new Error(result.error);
      }

      if ('status' in result && result.status !== 'SUCCESS') {
        throw new Error(result.message);
      }

      if ('data' in result) {
        const shortUrl = result.data.shortUrl;

        Alert.alert('AppLink Created', shortUrl);
      } else {
        throw new Error(
          result.message ?? 'No data returned from createAppLink'
        );
      }
    } catch (err: any) {
      console.log(err);
      Alert.alert('Error Creating Link', err.message || 'Unknown error');
    }
  };

  return (
    <View>
      <TextInput
        placeholder="Enter URL"
        value={linkParams.url}
        onChangeText={(text) => setLinkParams({ ...linkParams, url: text })}
      />
      <Button title="Create AppLink" onPress={handleCreateLink} />
    </View>
  );
};

Function 5: Get Referral Info

Use getReferralInfo to retrieve any referral data passed through a deep link.

import { Button } from 'react-native';
import { getReferralInfo } from 'appsonair-react-native-applink';

const App = () => {
  const handleReferralDetails = async () => {
    try {
      const info = await getReferralInfo();
      console.log('Referral Info', JSON.stringify(info, null, 2));
    } catch (err) {
      console.log('Error', JSON.stringify(err, null, 2));
    }
  };

  return <Button title="Get Referral Info" onPress={handleReferralDetails} />;
};