📱 universal-deep-link

A tiny JavaScript/TypeScript utility to open a mobile app via deep link if installed, and fallback to App Store / Play Store if not.
Works on iOS, Android, and desktop.

✨ Features

• ✅ Deep link into your app via a custom scheme (e.g. myapp://open)
• ✅ iOS App Store fallback using itms-apps://
• ✅ Android Play Store fallback using intent:// or market://
• ✅ Works in both plain JavaScript and TypeScript projects
• ✅ Configurable timeout for iOS fallback
• ✅ Lightweight (no dependencies)

📦 Installation

npm install smart-app-redirect

or with Yarn:

yarn add smart-app-redirect

🚀 Usage

Basic Example

import { openApp } from "smart-app-redirect";

openApp({
  scheme: "palm://open",
  ios: {
    appId: "6745506871",   // Your app's App Store ID
    country: "eg",         // Optional (default = "us")
  },
  android: {
    package: "com.palm.user", // Your app's Play Store package name
  },
  desktopUrl: "https://palm.com", // Fallback for desktop users
  timeout: 1500,                  // iOS fallback delay (ms)
  onFallback: (platform) => {
    console.log(`Fallback triggered on ${platform}`);
  },
});

iOS Configuration

You can pass either:

• appId (preferred) → builds a proper itms-apps://itunes.apple.com/app/id{appId} link
• storeUrl (optional) → use a custom App Store URL

Example:

ios: {
  appId: "6745506871",
  country: "us"
}

Android Configuration

You can pass either:

• package → builds an intent:// deep link with automatic Play Store fallback
• storeUrl → custom Play Store URL

Example:

android: {
  package: "com.palm.user"
}

Desktop Fallback

Optional desktopUrl if someone visits from a laptop/PC:

desktopUrl: "https://palm.com"

⚙️ API Reference

openApp(options: OpenAppOptions): void

OpenAppOptions

| Option | Type | Required | Description | |---------------|--------------------------|----------|-------------| | scheme | string | ✅ Yes | Deep link scheme (e.g. myapp://open) | | ios | IOSConfig | No | iOS config (App Store info) | | android | AndroidConfig | No | Android config (Play Store info) | | desktopUrl | string | No | Fallback URL for desktop users | | timeout | number | No | iOS fallback delay (default = 1500ms) | | onFallback | (platform: string) => void | No | Callback when fallback is triggered |

📱 Example: Palm App

openApp({
  scheme: "palm://open",
  ios: { appId: "6745506871", country: "eg" },
  android: { package: "com.palm.user" },
  desktopUrl: "https://palm.com",
});

📜 License

MIT © 2025 MSS