Smart Links

iOS Integration Overview

Adding the SDK to Your Xcode Project

The Smart Links iOS SDK is delivered as a Swift Package. Add it once to your project and it is available to all targets:

1. In Xcode, choose File → Add Package Dependencies…
2. Paste the repository URL into the search bar at the top right:
   https://github.com/rich-smartlynx/swift-framework
3. Leave the version rule as Up to Next Major Version starting from 1.1.2 and click Add Package.
4. In the package product chooser, make sure lynxapi is ticked and your app target is selected, then click Add Package again.

The package will appear under Package Dependencies in the Project Navigator. Xcode handles downloading, caching, and re-resolving the package automatically — there is nothing to add to a Podfile or Cartfile.

Initializing the Framework

Import lynxapi and create a single top-level Lynx instance with your API key. Your API key is shown in your Smart Links account settings. Declare it at file scope (outside any class or struct) so it is accessible from whichever lifecycle callback receives the link:

import lynxapi
let remote = Lynx(apiKey: "YOUR_API_KEY")

Calling checkForLink

remote.checkForLink(userActivity:completion:) is the single method you call in two situations:

• On every app launch — pass nil for userActivity. The framework fingerprints the device and returns any pending deferred link from a previous web visit — even before the user has installed the app.
• When a universal link opens the app — pass the NSUserActivity received from the system. The framework records the link for attribution tracking and returns it as a LinkResults.

The completion block is always called on a background thread — dispatch to DispatchQueue.main.async before touching UI.

LinkResults

The completion closure receives an optional LinkResults:

• link: String — the full URL including all query parameters
• confidence: Float — how certain the match is (see table below)
• openCount: Int — number of times checkForLink has been called for this device
• linkType — none, universal, deferred, previous_deferred, or previous_universal. If no link is present on this open but the device was previously seen with one, the last known link is returned.

Confidence Values

Attribution Tracking

Any query parameter whose name starts with utm_ is automatically recorded as an attribution parameter. No extra setup is needed — just include them in your Smart Links (e.g. ?utm_source=newsletter&utm_campaign=spring) and they will appear in your dashboard's Attribution Links section.

Entitlements & Associated Domains

iOS only opens a universal link in your app if two things are true: your app declares it can handle the domain, and the server at that domain publishes a file that names your app. Smart Links handles the server side automatically — you just need to configure Xcode.

Step 1 — Add the Associated Domains capability in Xcode:

1. Open your project in Xcode and select the project file in the Navigator (the blue icon at the top).
2. Select your app target from the target list on the left.
3. Click the Signing & Capabilities tab.
4. Click + Capability (top-left of the tab) and double-click Associated Domains.
5. A new Associated Domains section appears. Click the + button inside it and add:
   applinks:apps.smartlinks.mobi

Xcode writes this entry into your target's .entitlements file automatically. You do not need to edit the entitlements file by hand.

Step 2 — Nothing. The AASA file is already there.

iOS requires the server to host an apple-app-site-association (AASA) file at https://apps.smartlinks.mobi/.well-known/apple-app-site-association. This file lists which app bundle IDs and Team IDs are authorised to handle links on that domain. Smart Links generates and hosts this file automatically the moment you create your account — it is updated whenever you change your iOS bundle identifier or Team Identifier in your account settings. There is nothing to upload or configure on the server side.

When your app is installed and iOS sees a link to apps.smartlinks.mobi, it fetches the AASA file in the background, finds your bundle ID and Team ID in it, and from that point on routes matching links directly into your app instead of Safari.

Testing

Universal Links on a Physical Device

Build and install your app, then test a universal link by tapping it from outside your app — Safari, Notes, Mail, or Messages all work. Typing a URL directly into Safari's address bar will not trigger a universal link; iOS only intercepts links that are tapped, not navigated to manually.

When the link fires correctly a banner appears briefly at the top of Safari before the app opens. If the banner doesn't appear and Safari loads the page instead, see Troubleshooting below.

Universal Links in the Simulator

The Simulator supports universal links via the simctl command-line tool. Run this from Terminal — no physical device needed:

xcrun simctl openurl booted "https://apps.smartlinks.mobi/basename?param=value"

Replace basename with your app's base name and add any query parameters you want to test. The Simulator must already have your app installed.

Testing Deferred Links

A deferred link fires when checkForLink(userActivity: nil) is called on launch and the framework finds a fingerprint match from a previous web visit. To set one up:

1. Uninstall your app from the device or Simulator (this clears any existing state).
2. Open Safari and visit your Smart Link URL (e.g. https://apps.smartlinks.mobi/basename?utm_source=test). Safari (or the device's default browser) will capture a fingerprint and then redirect the user to the App Store, already pointing to your app. If the app is already installed, this same link will act as a universal link and open the app directly instead.
3. Install and launch your app. The call to checkForLink(userActivity: nil) in didFinishLaunchingWithOptions (or .task in SwiftUI) will return the link with a confidence value.

You can repeat this cycle as many times as needed — just uninstall between runs to reset the deferred link state. Each Simulator device has its own independent fingerprint, so you can run multiple scenarios in parallel using different Simulator devices.

Checking the Confidence Value

During development, log the full LinkResults so you can see exactly what the framework returns:

Troubleshooting

Link opens in Safari instead of the app

This is the most common issue. Work through these checks in order:

• Entitlement not saved. Open Xcode → Signing & Capabilities and confirm applinks:apps.smartlinks.mobi is present. It is easy to add it and accidentally close Xcode without the file being written to disk — check that your .entitlements file is committed to source control and contains the entry.
• Bundle ID or Team ID mismatch. The bundle ID and Team ID in your Smart Links account settings must exactly match what is in your Xcode target. A mismatch means the AASA file won't list your app and iOS will fall back to Safari.
• App not installed. Universal links only work when the app is already on the device. If the app is not installed, the link opens in Safari — this is expected iOS behaviour and is precisely why deferred links exist.
• Link tapped from address bar. Typing or pasting a URL into Safari's address bar bypasses universal link routing. The link must be tapped from somewhere — Notes, Mail, Messages, another app, or a web page.
• AASA cache. iOS fetches the AASA file via Apple's own CDN, not directly from the server, and the CDN can cache it for several hours. If you recently updated your bundle ID or Team ID, delete the app and reinstall to force iOS to re-validate the entitlement against the latest AASA.

checkForLink always returns nil or confidence 0

• Wrong API key. Double-check that the key in your code matches the one shown in your Smart Links account settings exactly — it is case-sensitive.
• No prior web visit. For a deferred link to be returned, someone must have visited a Smart Link URL from this device before the app was installed. If you are testing on a fresh Simulator or device without doing the Safari-visit step first, confidence 0 is the correct result.
• Network not available. checkForLink makes a network call. Confirm the device or Simulator has connectivity and that no firewall or VPN is blocking apps.smartlinks.mobi.

Cold launch works but warm resume doesn't (or vice versa)

• SceneDelegate pattern — missing one of the two entry points. With SceneDelegate you must implement both scene(_:willConnectTo:options:) (cold launch) and scene(_:continue:) (warm/background resume). Implementing only one means you will miss links in the other scenario.
• AppDelegate pattern with SceneDelegate present. If your Info.plist contains a scene configuration, iOS routes universal links to the SceneDelegate and application(_:continue:restorationHandler:) in the AppDelegate is never called. Remove the scene configuration or switch to the SceneDelegate pattern.

Universal links tapped inside the app open in Safari

This is intentional iOS behaviour — tapping a universal link within the same app (e.g. in a WKWebView or SFSafariViewController) always opens in Safari. If you need in-app link handling, intercept the URL in the web view's navigation delegate and call checkForLink directly rather than letting the system open it.

Everything looks correct but still not working

Apple provides a built-in diagnostic tool. On a physical device running iOS 16.4 or later, go to Settings → Developer → Universal Links → Diagnostics and enter your URL. It will tell you exactly why the link is or isn't being claimed by your app — including whether the AASA was fetched, whether the entitlement matched, and which app won the claim.

Android Integration Overview

Adding the SDK to Your Project

The Smart Links Android SDK is published on Maven Central. Add a single dependency line to your module-level build.gradle.kts:

dependencies {
    implementation("mobi.smartlinks:lynxapi:1.+")
}

The 1.+ version range automatically picks up the latest release within the 1.x series. Gradle resolves it from Maven Central — there is no extra repository to add.

Manifest Permissions

Add the following to your AndroidManifest.xml. The INTERNET permission is required for the checkForLink network call. The <queries> block lets the library detect the device's default browser for fingerprinting:

<!-- Required for checkForLink network calls -->
<uses-permission android:name="android.permission.INTERNET" />

<!-- Allow the library to detect the default browser -->
<queries>
    <intent>
        <action android:name="android.intent.action.VIEW" />
        <category android:name="android.intent.category.BROWSABLE" />
        <data android:scheme="https" />
    </intent>
</queries>

Initializing the SDK

Import mobi.smartlinks.lynxapi.Lynx and create a single top-level Lynx instance with your API key. Your API key is shown in your Smart Links account settings. Declare it at file scope (outside any class) so it is accessible from both onCreate and onNewIntent:

Calling checkForLink

remote.checkForLink(context, intent, completion) is the single method you call in two situations:

• On every app launch — pass the launching intent from onCreate(). If the intent has no link data, the SDK fingerprints the device and returns any pending deferred link from a previous web visit.
• When an App Link opens the app while it is running — pass the new intent from onNewIntent(). The SDK records the link for attribution tracking and returns it as a LinkResults.

The completion callback is called on a background thread — use runOnUiThread { } before touching UI.

LinkResults

The completion lambda receives an optional LinkResults:

• link: String — the full URL including all query parameters
• confidence: Float — how certain the match is (see table below)
• openCount: Int — number of times checkForLink has been called for this install
• linkType: LynkType — NONE, UNIVERSAL, DEFERRED, PREVIOUS_DEFERRED, or PREVIOUS_UNIVERSAL. If no link is present on this open but the device was previously seen with one, the last known link is returned.

Confidence Values

Attribution Tracking

Any query parameter whose name starts with utm_ is automatically recorded as an attribution parameter. No extra setup is needed — just include them in your Smart Links (e.g. ?utm_source=newsletter&utm_campaign=spring) and they will appear in your dashboard's Attribution Links section.

App Links & Digital Asset Links

Android only opens an App Link directly in your app if two things are true: your manifest declares an intent filter with android:autoVerify="true", and the server at that domain publishes a Digital Asset Links JSON file that names your app. Smart Links handles the server side automatically — you just need to configure your manifest.

Step 1 — Add the App Links intent filter to your Activity:

<activity
    android:name=".MainActivity"
    android:exported="true"
    android:launchMode="singleTask">

    <!-- Standard launcher intent -->
    <intent-filter>
        <action android:name="android.intent.action.MAIN" />
        <category android:name="android.intent.category.LAUNCHER" />
    </intent-filter>

    <!-- App Links 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="https"
            android:host="apps.smartlinks.mobi" />
    </intent-filter>

</activity>

The android:launchMode="singleTask" attribute ensures that tapping a link while the app is running calls onNewIntent() rather than creating a second Activity instance.

The android:autoVerify="true" attribute tells the OS to verify your app owns the domain via the Digital Asset Links JSON file at https://apps.smartlinks.mobi/.well-known/assetlinks.json.

Step 2 — Nothing. The assetlinks.json file is already there.

Android requires the server to host an assetlinks.json file at https://apps.smartlinks.mobi/.well-known/assetlinks.json. This file lists which app package names and signing certificate fingerprints are authorised to handle links on that domain. Smart Links generates and hosts this file automatically the moment you create your account — it is updated whenever you change your package name or signing certificate in your account settings. There is nothing to upload or configure on the server side.

When your app is installed, Android fetches the assetlinks.json file, finds your package name and certificate fingerprint in it, and from that point on routes matching links directly into your app instead of Chrome.

Testing

App Links on a Physical Device

Build and install your app, then test an App Link by tapping it from outside your app — Chrome, Gmail, Messages, or any other app. Typing a URL directly into Chrome's address bar will not trigger an App Link; Android only intercepts links that are tapped, not navigated to manually.

When the link fires correctly the app opens immediately — no browser chooser dialog appears. If Chrome opens instead, see Troubleshooting below.

App Links via ADB

You can test App Links from the command line using adb. Run this from Terminal — works with both physical devices and emulators:

adb shell am start -a android.intent.action.VIEW \
    -d "https://apps.smartlinks.mobi/basename?param=value" \
    your.package.name

Replace basename with your app's base name, your.package.name with your application ID, and add any query parameters you want to test.

Testing Deferred Links

A deferred link fires when checkForLink is called on launch and the SDK finds a fingerprint match from a previous web visit. To set one up:

1. Uninstall your app from the device or emulator (this clears any existing state).
2. Open Chrome and visit your Smart Link URL (e.g. https://apps.smartlinks.mobi/basename?utm_source=test). Chrome will capture a fingerprint and redirect the user to the Play Store. If the app is already installed, this same link will act as an App Link and open the app directly.
3. Install and launch your app. The call to checkForLink in onCreate() will return the link with a confidence value.

You can repeat this cycle as many times as needed — just uninstall between runs to reset the deferred link state. Each emulator AVD has its own independent fingerprint, so you can run multiple scenarios in parallel using different emulators.

Checking the Confidence Value

During development, log the full LinkResults so you can see exactly what the SDK returns:

Troubleshooting

Link opens in Chrome instead of the app

This is the most common issue. Work through these checks in order:

• Intent filter not verified. Open your manifest and confirm the intent filter has android:autoVerify="true" with the correct android:host. The data scheme must be https.
• Package name or certificate mismatch. The package name and signing certificate fingerprint in your Smart Links account settings must exactly match your app. A mismatch means the assetlinks.json file won't list your app and Android will fall back to Chrome.
• App not installed. App Links only work when the app is already on the device. If the app is not installed, the link opens in the browser — this is expected behaviour and is precisely why deferred links exist.
• Debug vs Release signing. If you test with a debug build, the signing certificate is different from your release certificate. Make sure the fingerprint in your Smart Links account matches whichever build type you are testing.
• Link tapped from address bar. Typing or pasting a URL into Chrome's address bar bypasses App Link routing. The link must be tapped from somewhere — Gmail, Messages, another app, or a web page.

checkForLink always returns null or confidence 0

• Wrong API key. Double-check that the key in your code matches the one shown in your Smart Links account settings exactly — it is case-sensitive.
• No prior web visit. For a deferred link to be returned, someone must have visited a Smart Link URL from this device before the app was installed. If you are testing on a fresh emulator without doing the Chrome-visit step first, confidence 0 is the correct result.
• Network not available. checkForLink makes a network call. Confirm the device or emulator has connectivity and that no firewall or VPN is blocking apps.smartlinks.mobi.
• Missing INTERNET permission. Confirm your manifest includes <uses-permission android:name="android.permission.INTERNET" />.

Cold launch works but warm resume doesn't (or vice versa)

• Missing onNewIntent. You must handle both onCreate() (cold launch) and onNewIntent() (warm/background resume). Implementing only one means you will miss links in the other scenario.
• Launch mode not set. Without android:launchMode="singleTask" in your manifest, tapping a link while the app is running creates a second Activity instance instead of calling onNewIntent(). Add the attribute to your Activity declaration.
• setIntent not called. After receiving a new intent in onNewIntent(), call setIntent(intent) to keep getIntent() in sync.

Verifying App Link status

Android provides a built-in diagnostic tool. Run this from Terminal to check whether your app is verified for the domain:

adb shell pm get-app-links your.package.name

Look for apps.smartlinks.mobi in the output with a status of verified. If it shows none or legacy_failure, the assetlinks.json verification failed — check your package name and certificate fingerprint.

Short Links API

Overview

The Short Links API lets you programmatically create shortened Smart Links from your backend server. Each short link maps a compact 4-character code to a full Smart Link URL, preserving all query parameters for deep linking and attribution.

Short links follow the format https://apps.smartlinks.mobi/basename/code — for example https://apps.smartlinks.mobi/myapp/Hg5d. When visited, the short link expands to the original full URL and behaves exactly like a regular Smart Link, including deferred deep linking and attribution tracking.

Endpoint

POST https://apps.smartlinks.mobi/create_short_link

Authentication

Pass your obfuscated API key in the api_key field of the JSON request body. You can retrieve your key using the button at the bottom of this page.

Request Body

Response

On success, the API returns:

Redirect Types

Passthrough (redirect_type: 0)

The default. The short link expands and is processed as a normal Smart Link — the visitor goes through the standard flow (app detection, deferred deep linking, store redirect, attribution tracking). Use this when you want the full Smart Links experience.

301 Redirect (redirect_type: 1)

The short link immediately issues an HTTP 301 redirect to the full URL. The browser navigates directly to the expanded URL. This skips the Smart Links processing flow — use it when you just need a short URL without deep linking, for example in SMS or print materials where you only need URL shortening.

Your API Key

Click the button below to retrieve your obfuscated API key. Copy it into your backend server code to authenticate Short Link API calls. Do not share this key publicly or embed it in client-side applications.

You must be logged in to retrieve your API key.

Remote Logging

Overview

The Smart Links SDK includes a built-in remote logging facility that streams log messages from your app directly to your Smart Links dashboard. When enabled, every call to remoteLog() in your app sends the message to the server where it can be viewed and downloaded in real time.

This is designed for pre-release testing or to temporarily enable on a production build when debugging a specific issue. It is not intended to be left on permanently — it adds a network call for every log message and the server retains logs for a limited time.

How It Works

1. In your Smart Links account settings, set the Remote Log Version field to the CFBundleShortVersionString (iOS) or versionName (Android) of the build you want to debug — for example 1.2.3.
2. When that build calls checkForLink, the SDK sends its app version to the server. If it matches the configured version, the server responds with remoteLogEnabled: true.
3. From that point on, every remoteLog() call in the app POSTs the message to the Smart Links server. The logs appear in the Remote Logs section of your dashboard.
4. When you are done debugging, clear the version field in your account settings. The next time the app calls checkForLink, remote logging will be disabled.

Local vs Remote

remoteLog() writes to the local device log (Xcode Console / Android Logcat) when a level is provided. Omit it to send remotely without local output. The remote part is gated entirely by the version match on the server — regardless of whether a level is specified. This means you can sprinkle remoteLog() calls throughout your code during development and they cost nothing in production until you explicitly turn remote logging on.

API Reference

iOS — Swift

The level parameter is optional. Omit it to send remotely without writing to the local console.

Android — Kotlin

The level parameter is optional. Omit it to send remotely without writing to Logcat.

Best Practices

When to Use Remote Logging

• Pre-release testing — enable it on your TestFlight or internal test build to verify deep link handling, attribution parameters, and app launch flows without needing the device connected to Xcode or Android Studio.
• Production debugging — if a user reports an issue you cannot reproduce, set their app version as the remote log version, ask them to open the app, and review the logs in your dashboard.

When Not to Use Remote Logging

• Always-on production logging — every remoteLog() call makes a network request. Leaving it enabled permanently wastes bandwidth and battery. Turn it off as soon as you have the information you need.
• Sensitive data — do not log PII, tokens, or credentials via remoteLog(). The messages are transmitted over HTTPS but are stored in plain text on the server.

Tips

• Use meaningful log levels — filter by ERROR or WARN in the dashboard to quickly find problems.
• Include context in your messages (screen name, user action, relevant parameter values) so you can reconstruct what happened without guessing.
• Remember that remoteLog() is only activated after checkForLink runs. Any log calls before that point will only appear locally.