nativeredirect

NativeRedirect

A minimal, zero-dependency utility for redirecting mobile web users to native apps (deep linking) with a web fallback.

Features

• TypeScript-first: Fully typed API.
• Zero Dependencies: Lightweight ES module.
• Privacy Focused: No analytics or tracking code.
• Safe Fallbacks: Automatically handles failures by falling back to web URLs.
• Platform Aware: Detects iOS vs Android and builds appropriate intent URLs or custom schemes.
• In-App Browser Handling: Intentionally aborts on Instagram/Facebook in-app browsers to avoid trapping users.

Usage

import { redirect } from 'nativeredirect';

redirect({
  // The current web URL (used for query param parsing and default fallback)
  url: window.location.href,
  
  // Custom Scheme for iOS
  ios: {
    scheme: 'myapp', // resulting URL: myapp://path?query
    path: 'products/123' // Optional override
  },
  
  // Intent URL for Android
  android: {
    scheme: 'myapp',
    packageName: 'com.example.myapp'
  },
  
  // Fallback URL if app is not installed (defaults to `url` above)
  fallback: 'https://example.com/download'
});

How It Works

• Detection: usage of navigator.userAgent and navigator.platform to determine if the user is on iOS or Android.
• Link Generation:
  • iOS: scheme://path?query
  • Android: intent://path?query#Intent;scheme=scheme;package=com.example;end;
• Execution: Uses window.location.assign.
• Fallback: Sets a timeout (default 1500ms). If the browser remains visible (meaning the app didn't open), it redirects to the fallback URL.

Limitations

• Dialog Prompts: Browsers may show a "Open in..." dialog which cannot be detected programmatically.
• In-App Browsers: Deep linking often fails inside apps like Instagram or Messenger. This library aborts redirect calls in these environments to keep the user on the web.
• Reliability: Browser security policies change frequently. 100% success rate for deep linking without Universal Links / App Links is not possible.

Roadmap

• Support for Universal Links / App Links validation (server-side helper).
• Configurable in-app browser allow-list.
• Custom timeout configurations per platform.