StageUp
Mobile SDKDeep Link

React Native Deep Link

This guide describes how to implement deep links in a React Native application using the NBase AdStage SDK.

1. Overview

  • A deep link is a URL that takes users directly to a specific screen in your app.
  • The AdStage SDK provides deep link creation, handling, and tracking.

2. Quick start

2.1 Install SDK

npm install nbase-ad-react-native-sdk
# or
yarn add nbase-ad-react-native-sdk
 
# iOS extra step
cd ios && pod install

2.2 Basic setup

Android setup

android/app/src/main/java/.../MainActivity.java:

import android.content.Intent;
import android.os.Bundle;
import com.facebook.react.ReactActivity;
import io.nbase.adapter.adstage.AdStageSDK;
 
public class MainActivity extends ReactActivity {
    @Override
    protected void onCreate(Bundle savedInstanceState) {
        super.onCreate(savedInstanceState);
 
        // Set API key
        AdStageSDK.setApiKey("YOUR_API_KEY");
 
        // Handle deep link on app launch
        handleDeepLink(getIntent());
    }
 
    @Override
    protected void onNewIntent(Intent intent) {
        super.onNewIntent(intent);
        setIntent(intent);
        handleDeepLink(intent);
    }
 
    private void handleDeepLink(Intent intent) {
        if (intent != null) {
            AdStageSDK.handleDeepLink(intent);
        }
    }
 
    @Override
    protected String getMainComponentName() {
        return "AdStageSDKReactNativeSample";
    }
}

android/app/src/main/AndroidManifest.xml:

<activity
        android:name=".MainActivity"
        android:exported="true"
        android:launchMode="singleTop">
 
        <!-- Deep link intent filter -->
        <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="your-app-scheme" />
        </intent-filter>
</activity>

iOS setup

ios/<Project>/Info.plist:

<key>CFBundleURLTypes</key>
<array>
        <dict>
                <key>CFBundleURLName</key>
                <string>nbase-adstage</string>
                <key>CFBundleURLSchemes</key>
                <array>
                        <string>your-app-scheme</string>
                </array>
        </dict>
        <!-- Add additional schemes if needed -->
</array>

ios/<Project>/AppDelegate.mm:

#import "AppDelegate.h"
#import "<Project>-Swift.h"

@implementation AppDelegate

- (BOOL)application:(UIApplication *)application didFinishLaunchingWithOptions:(NSDictionary *)launchOptions
{
    self.moduleName = @"AdStageSDKReactNativeSample";
    self.initialProps = @{};

    // Initialize AdStage
    [AdStageInitializer load];

    return [super application:application didFinishLaunchingWithOptions:launchOptions];
}

- (BOOL)application:(UIApplication *)application openURL:(NSURL *)url options:(NSDictionary<UIApplicationOpenURLOptionsKey,id> *)options
{
    // Handle AdStage deep link
    [AdStageInitializer handleDeepLink:url];

    return [super application:application openURL:url options:options];
}

@end

3. React Native implementation

import { AdStageSDK } from 'nbase-ad-react-native-sdk';
 
class App extends Component {
  componentDidMount() {
    this.setupDeepLinkListener();
    this.checkPendingDeepLink?.();
  }
 
  setupDeepLinkListener() {
    // Register AdStage deep link listener
    AdStageSDK.addDeepLinkListener((event) => {
      console.log('Deep link received:', event.path);
      console.log('Parameters:', event.parameters);
      // TODO: Route based on deep link
    });
  }
}

Create deep links for sharing or marketing within your app.

import { AdStageSDK } from 'nbase-ad-react-native-sdk';
import { Share } from 'react-native';
 
const createAndShareDeepLink = async () => {
  try {
    const deepLinkResult = await AdStageSDK.createDeepLink({
      path: '/product',
      parameters: {
        productId: '12345',
        category: 'electronics',
        utm_source: 'app_share',
        utm_medium: 'social',
      },
    });
 
    if (deepLinkResult.success) {
      console.log('Created deep link:', deepLinkResult.url);
      await Share.share({
        message: `Check out this product! ${deepLinkResult.url}`,
        url: deepLinkResult.url,
        title: 'Share Product',
      });
    }
  } catch (error) {
    console.error('Failed to create deep link:', error);
  }
};
 
// Examples
const createUserProfileDeepLink = async (userId) => {
  const result = await AdStageSDK.createDeepLink({
    path: '/user',
    parameters: { userId, from: 'profile_share' },
  });
  return result.url;
};
 
const createPromotionDeepLink = async (promotionId) => {
  const result = await AdStageSDK.createDeepLink({
    path: '/promotion',
    parameters: {
      promotionId,
      utm_campaign: 'summer_sale_2024',
      utm_medium: 'deeplink',
    },
  });
  return result.url;
};

4. Testing

4.1 ADB (Android)

# Test deep link
adb shell am start \
  -W -a android.intent.action.VIEW \
  -d "your-app-scheme://product?id=123" \
  your.package.name
 
# Deep link with parameters
adb shell am start \
  -W -a android.intent.action.VIEW \
  -d "your-app-scheme://user?userId=456&name=test" \
  your.package.name

4.2 iOS Simulator

# Test deep link on iOS simulator
xcrun simctl openurl booted "your-app-scheme://product?id=123"
 
# Test via Safari
xcrun simctl openurl booted "https://your-domain.com/redirect?deeplink=your-app-scheme://product?id=123"

5. Troubleshooting

Deep link not received

  • Ensure URL scheme is correctly set in AndroidManifest.xml and Info.plist
  • Ensure native initialization (e.g., AdStageInitializer.load()) is completed
  • Ensure deep link listener is properly registered

Android deep link issues

  • Check onNewIntent implementation in MainActivity
  • Verify android:launchMode="singleTop"
  • Test in background/terminated states

iOS deep link issues

  • Verify application:openURL:options: implementation
  • Ensure AdStageInitializer.load() is called
  • Check URL Schemes settings

Build errors

  • Re-run npm install && cd ios && pod install
  • Clear cache: npx react-native start --reset-cache

Table of Contents