Deep Links

Deep links route a short-URL click straight into a specific screen of your native iOS or Android app, with sane fallbacks for users without the app installed. Codelloy handles platform detection, App Store / Play Store fallbacks, and the optional fallbackUrl chain for you.

What deep links do

• Open your app at a specific screen (product, profile, event) instead of dumping the user on your home page.
• Route to App Store / Play Store when the app isn’t installed.
• Skip onboarding by carrying context (e.g. a coupon code) into the app.
• Track per-link analytics — clicks, scans, device breakdown — alongside web traffic.

How Codelloy resolves a deep link at click time

1. Detect platform — iOS vs Android vs desktop browser.
2. Look up the matching deepLinks[] entry by the registered MobileApp’s platform.
3. Try the deep-link URL (deeplinkUrl). If the app is installed and registered for the scheme, the OS opens it.
4. On app-not-installed — fall back to either the fallbackUrl (when fallbackEnabled=true) or the registered Store URL.
5. On desktop or no matching entry — go straight to the plain url.

One-time setup — register your apps

Before you can attach deepLinks[] to a short URL, register each app on the Codelloy dashboard. See Mobile Apps for the walkthrough — it takes about two minutes and produces a 12-character mobileAppId per platform that you’ll reference in API requests.

Three fields per registered app:

The mobileAppId itself is generated server-side on save and surfaced read-only with a copy button on each saved row.

Creating a deep-linked short URL via API

Each deepLinks[] entry binds a registered mobileAppId to a per-platform deep-link configuration. See API Endpoints for the full request schema.

E-commerce product link

curl -X POST https://api.codelloy.com/link/external/v1/shortenedUrl/save \
  -H "X-API-KEY: your_api_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://example.com/product/123",
    "shortCode": "product123",
    "shortLinkName": "Spring sale — product 123",
    "deepLinks": [
      {
        "mobileAppId": "abc123def456",
        "deeplinkUrl": "myapp://product/123",
        "fallbackUrl": "https://example.com/product/123",
        "linkBehaviour": "app",
        "fallbackEnabled": true
      },
      {
        "mobileAppId": "789xyz456ghi",
        "deeplinkUrl": "myapp://product/123",
        "fallbackUrl": "https://example.com/product/123",
        "linkBehaviour": "app",
        "fallbackEnabled": true
      }
    ]
  }'

User profile link

curl -X POST https://api.codelloy.com/link/external/v1/shortenedUrl/save \
  -H "X-API-KEY: your_api_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://example.com/users/456",
    "shortCode": "user456",
    "shortLinkName": "User profile — 456",
    "deepLinks": [
      {
        "mobileAppId": "abc123def456",
        "deeplinkUrl": "myapp://profile/456",
        "fallbackUrl": "https://example.com/users/456",
        "linkBehaviour": "app",
        "fallbackEnabled": true
      },
      {
        "mobileAppId": "789xyz456ghi",
        "deeplinkUrl": "myapp://profile/456",
        "fallbackUrl": "https://example.com/users/456",
        "linkBehaviour": "app",
        "fallbackEnabled": true
      }
    ]
  }'

Per-entry behaviour controls

storeUrl and platform on each deepLinks[] entry are response-only fields. They reflect the registered MobileApp at read time — you don’t send them in request bodies. Edit the registered app on the dashboard to update them globally. See Field Reference.

What happens when mobileAppId is missing or invalid?

Best practices

1. Register both platforms — if your app ships on iOS and Android, register both and include both in deepLinks[]. Asymmetric deployment (e.g. iOS-only) is supported but the missing platform redirects to plain url, not the store.
2. Provide fallbackUrl that resolves to a meaningful page (the same content as url or a richer marketing page) so users without the app still get value.
3. Test on real devices — iOS Safari, Android Chrome, in-app webviews (Slack, Twitter, LinkedIn) all handle deep links slightly differently. Codelloy abstracts most of this but device-specific edge cases exist.
4. Use analytics — every click is tracked, including device class and the resolution path (deep link fired vs. store fallback vs. plain web). See Analytics.
5. Update MobileApp.storeUrl centrally — change once on the dashboard, every existing short URL reflects the new value on the next click. No re-saving short URLs needed.