Skip to main content

Deep Linking

Deep linking enables seamless navigation to specific in-app content, enhancing user engagement by directing users to targeted screens within your React Native application. The AppTrove React Native SDK supports two types of deep linking: Normal Deep Linking (for users with the app installed) and Deferred Deep Linking (for users who install the app via a deep link). This section outlines the setup and implementation for both Android and iOS platforms.

Prerequisites​

  • AppTrove React Native SDK installed and initialized in your project
  • A Trackier MMP account with access to the Trackier Panel
  • React Native 0.60 or later
  • For Android:
    • Android API 21 (Android 5.0) or later
  • For iOS:
    • iOS 10.0 or later
    • Xcode 12.0 or later
  • Basic knowledge of JavaScript, React Native, and platform-specific configurations (e.g., AndroidManifest.xml, Xcode)

Overview​

Deep linking redirects users to specific app content using URLs. The AppTrove SDK handles two scenarios:

  • Normal Deep Linking: When the app is already installed, the deep link opens the app and navigates to the specified screen.
  • Deferred Deep Linking: When the app is not installed, the deep link directs users to the app store. After installation, the SDK navigates to the specified screen upon first app launch.

Normal Deep Linking​

Normal deep linking allows users with the app installed to open specific app screens directly via a deep link URL. Configuration is required for both Android and iOS.

Android Configuration​

To handle deep links on Android, configure an activity in the AndroidManifest.xml file to respond to deep link URLs.

Step 1: Update AndroidManifest.xml​
  1. Open the android/app/src/main/AndroidManifest.xml file in your React Native project.
  2. Add an activity with an intent-filter to handle deep links, specifying a unique scheme and host.
Example AndroidManifest.xml​
AndroidManifest.xml
<activity
    android:name=".Activity.FirstProduct"
    android:exported="true">
    <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="trackier.u9ilnk.me"
            android:pathPrefix="/product"
            android:scheme="https" />
    </intent-filter>
</activity>
https://trackier.u9ilnk.me/product?dlv=FirstProduct&quantity=10&pid=sms
  1. Build your React Native project for Android using npm run android.
  2. Install the APK on a device or emulator.
  3. Open the deep link URL in a browser or via an ad to verify it opens the specified activity.

iOS Configuration​

For iOS, configure Universal Links to enable deep linking, allowing the app to open directly from web URLs.

Step 1: Get App Bundle ID and Prefix ID​
  1. Log into your Apple Developer Account.
  2. Navigate to Certificates, IDs & Profiles > Identifiers > App IDs.
  3. Select your app and copy the Prefix ID and App Bundle ID.
Step 2: Add IDs in Trackier MMP​
  1. Log in to your Trackier Panel.
  2. Select your application and click the Action button.
  3. Navigate to UniLink in the Dashboard.
  4. Create a template by clicking the Action button in the header.
  5. Edit the template and add the Prefix ID and App Bundle ID under Link Behaviour (When application is installed).

App Bundle ID and Prefix ID

Step 3: Configure Associated Domains in Xcode​
  1. Build your React Native project for iOS using npm run ios or open the ios/[YourAppName].xcworkspace file in Xcode.
  2. In Xcode, select your project and target.
  3. Go to the Capabilities tab and enable Associated Domains.
  4. Add the unilink subdomain from the Trackier MMP app settings in the format: applinks:subdomain.unilink.me.
note

Trackier hosts the apple-app-site-association file to support Universal Links. Ensure the unilink subdomain is correctly configured in both Trackier MMP and Xcode.

  1. Build and install the app on an iOS device or simulator.
  2. Open a Universal Link (e.g., https://yourbrand.u9ilnk.me) in Safari to verify it opens the app.

Deferred Deep Linking​

Deferred deep linking directs users to the app store if the app is not installed. After installation, the SDK navigates to the specified screen upon first app launch. This requires setting a callback to handle the deep link URL.

Steps to Implement Deferred Deep Linking​

  1. Capture Deep Link Data in Use effect, capture the deep link url and forward it to TrackierSdk.
  2. Configure a callback listener on the TrackierConfig object using setDeferredDeeplinkCallbackListener.
  3. Initialize the SDK with the configured TrackierConfig.
  4. Handle the deep link URL in the callback to navigate to the desired screen.
JavaScript Example​
App.js
  useEffect(() => {
    const getUrlAsync = async () => {
      // Get the deep link used to open the app
      const initialUrl = await Linking.getInitialURL();
      // Sent this url to Trackier Sdk
      TrackierSDK.parseDeepLink(initialUrl);
      // The setTimeout is just for testing purpose
      setTimeout(() => {
        setUrl(initialUrl);
        setProcessing(false);
      }, 1000);
    };

    getUrlAsync();
  }, []);
App.js
import React from 'react';
import { TrackierConfig, TrackierSDK } from 'react-native-trackier';
import { StyleSheet, Text, View, TouchableHighlight } from 'react-native';

export default function App() {
  // Initialize SDK with Deferred Deep Linking
  const trackierConfig = new TrackierConfig("abcf2270-xxxxxxx-xxxx-34903c6e1d53", TrackierConfig.EnvironmentDevelopment);
  trackierConfig.setDeferredDeeplinkCallbackListener(function(uri) {
    console.log("Deferred Deeplink Callback received");
    console.log("URL: " + uri);
    // Add logic to navigate to the specified screen based on uri
  });
  TrackierSDK.initialize(trackierConfig);

  return (
    <View style={styles.container}>
      <Text>AppTrove React Native SDK</Text>
    </View>
  );
}

const styles = StyleSheet.create({
  container: {
    flex: 1,
    alignItems: 'center',
    justifyContent: 'center',
  },
});

Expected Outcome​

When a user installs the app via a deep link, the setDeferredDeeplinkCallbackListener callback receives the deep link URL, allowing you to navigate to the specified content after the app launches.

Best Practices​

  • Test Deep Links Thoroughly: Test both normal and deferred deep links on Android and iOS to ensure correct navigation.
  • Use Unique Schemes for Android: Choose a unique android:scheme value in AndroidManifest.xml to avoid conflicts with other apps.
  • Secure Unilink Subdomain: Verify the unilink subdomain is correctly configured in Trackier MMP and Xcode to prevent Universal Link failures.
  • Handle Null URLs: Add fallback logic in the deferred deep link callback to handle cases where uri is null or undefined.
  • Log Deep Link Data: Use console.log to verify deep link URLs during development.
  • Comply with Privacy Regulations: Ensure deep link data handling complies with GDPR, CCPA, and other privacy laws.

Troubleshooting​

  • Deep Links Not Opening App (Android):
    • Verify the AndroidManifest.xml intent-filter configuration matches the deep link URL structure.
    • Ensure android:exported="true" is set for the activity.
    • Test the deep link URL in a browser or via an ad.
  • Universal Links Not Working (iOS):
    • Confirm the applinks:subdomain.unilink.me entry is correct in Xcode's Associated Domains.
    • Check that the apple-app-site-association file is hosted by Trackier and accessible.
    • Ensure the Prefix ID and App Bundle ID are correctly set in Trackier MMP.
  • Deferred Deep Link Callback Not Triggered:
    • Verify the setDeferredDeeplinkCallbackListener method is called before TrackierSDK.initialize.
    • Test the deferred deep link by uninstalling the app, clicking the deep link, and installing via the app store.
    • Check console logs for errors in the callback.
  • General Issues:

The AppTrove React Native SDK provides a resolveDeeplinkUrl method to resolve deferred deep links and get instant access to the deep link URL.

Deep Link Resolver Example
import { TrackierSDK } from 'react-native-trackier';

// Resolve a deep link URL
TrackierSDK.resolveDeeplinkUrl("https://trackier58.u9ilnk.me/d/NKmWH9E7b1")
  .then(result => {
    console.log("Resolved URL:", result);
    // Handle the resolved deep link
    handleResolvedDeepLink(result);
  })
  .catch(error => {
    console.error("Failed to resolve deep link:", error);
  });

// Handle the resolved deep link
function handleResolvedDeepLink(resolvedUrl) {
  console.log("Resolved Deep Link URL:", resolvedUrl);
  // Add your navigation logic here
}

Example Implementation​

App.js
import React, { useEffect } from 'react';
import { TrackierConfig, TrackierSDK } from 'react-native-trackier';

export default function App() {
  useEffect(() => {
    // Initialize SDK
    const trackierConfig = new TrackierConfig("your-app-token", TrackierConfig.EnvironmentDevelopment);
    TrackierSDK.initialize(trackierConfig);
    
    // Example: Resolve a deep link URL
    resolveExampleDeepLink();
  }, []);

  const resolveExampleDeepLink = () => {
    const deepLinkUrl = "https://trackier58.u9ilnk.me/d/NKmWH9E7b1";
    
    TrackierSDK.resolveDeeplinkUrl(deepLinkUrl)
      .then(result => {
        console.log("Successfully resolved deep link:", result);
      })
      .catch(error => {
        console.error("Failed to resolve deep link:", error);
      });
  };

  return (
    <View style={styles.container}>
      <Text>AppTrove React Native SDK</Text>
    </View>
  );
}

For further assistance, refer to the Trackier Documentation Portal or contact Trackier support at support@trackier.com.