> ## Documentation Index
> Fetch the complete documentation index at: https://docs.dashlink.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# iOS SDK

> Install the Dashlink iOS SDK, receive Universal Links, and recover the original content after an App Store install.

Routing (opening an already-installed app from `https://yourbrand.dshl.in/Ab12Cd`) is a Universal Link and does **not** require this SDK. Recovering the original content after an App Store install, and joining that first open to the store tap, **does**.

```swift theme={null}
DynamicLinks.configure(apiKey: "dlk_sdk_…")
DynamicLinks.shared.handleUniversalLink(url) { link, error in
    link?.appUrl  // plus utm*, isDeferred, clickId
}

// first launch after install:
DynamicLinks.shared.performDeferredCheckIfNeeded { link, error in
    // pasteboard recovery
}
```

The SDK resolves Universal Links and recovers the original destination on first open after an App Store install, joining that open to the same `click_id` as the store tap.

## When you need the SDK

| You have | Use |
| - | - |
| App installed, Dynamic Link host declared, OS verified | The OS delivers the short URL. Parse it, or call JSON resolve. The SDK is optional. |
| First open after an App Store install from a Dynamic Link | Keep the SDK. It reads the pasteboard, navigates to `appUrl`, and publishes `deferred_open` with the same `click_id` as the store tap. |
| Later launches | Deferred is not re-run. |

Without the SDK, a fresh install opens on the home screen and the store tap cannot be joined to first open. See [Receive](https://docs.dashlink.ai/guides/app-dynamic-links/receive.md) for the routing vs deferred map.

## Install

### Swift Package Manager

In Xcode: **File → Add Package Dependencies** → `https://github.com/Dashlink-ai/dashlink-ios.git` from `1.0.0`. Add the `Dashlink` product to your app target.

Or in `Package.swift`:

```swift theme={null}
.package(url: "https://github.com/Dashlink-ai/dashlink-ios.git", from: "1.0.0")
```

### CocoaPods

```ruby theme={null}
pod 'Dashlink', '~> 1.0.0'
```

## Dynamic Link API key

JSON resolve that writes tracking requires a **Dynamic Link** API key. REST keys (`dlk_live_`) are rejected.

1. In the dashboard, go to **Settings → API Keys → Type Dynamic Link**.
2. Copy the `dlk_sdk_…` key once and call `DynamicLinks.configure(apiKey:)` before `handleUniversalLink` / `performDeferredCheckIfNeeded`.
3. The SDK sends it as `X-API-Key` (header only). A leaked IPA key can hit that org's resolve URL; it cannot call the dashboard REST API.

See [API keys](https://docs.dashlink.ai/guides/api-keys.md).

```swift theme={null}
DynamicLinks.configure(apiKey: "dlk_sdk_…")
```

`configure` rejects keys that do not start with `dlk_sdk_`.

## Declare the Dynamic Link host

Dashlink already hosts the Apple app site association file on the Dynamic Link domain. The app must still declare that **host**. Associated Domains must include `applinks:` plus `{subdomain}.dshl.in`, not only the marketing site.

```
applinks:yourbrand.dshl.in
```

Without Associated Domains, Safari never hands the tap to the app. The SDK cannot invent OS intercept. After adding the entitlement, delete and reinstall so iOS refetches the association file — an update is not always enough.

AASA paths, Auto vs Manual mode, and Team ID format live on [App association](https://docs.dashlink.ai/guides/app-dynamic-links/app-association.md).

## Receive Universal Links

```swift theme={null}
func application(
    _ application: UIApplication,
    continue userActivity: NSUserActivity,
    restorationHandler: @escaping ([UIUserActivityRestoring]?) -> Void
) -> Bool {
    guard userActivity.activityType == NSUserActivityTypeBrowsingWeb,
          let url = userActivity.webpageURL else { return false }
    DynamicLinks.configure(apiKey: "dlk_sdk_…")
    DynamicLinks.shared.dynamicLinkHosts = ["yourbrand.dshl.in"]
    DynamicLinks.shared.handleUniversalLink(url) { link, error in
        guard let appUrl = link?.appUrl else { return }
        // Route to the screen for appUrl
    }
    return true
}
```

Scene-based apps use `scene(_:continue:)` with the same `webpageURL`.

`dynamicLinkHosts` restricts which https URLs the SDK treats as Dashlink short URLs.

On an installed tap the SDK JSON-resolves the short URL (`deferred=0`, `match=direct`), returns `appUrl`, and analytics records `app_open`. The query parameters the SDK sends are listed on [Receive](https://docs.dashlink.ai/guides/app-dynamic-links/receive.md).

## Deferred first-open

When the app is missing, Dashlink shows a store interstitial that **copies** the short URL (with `dl_cid`) to the pasteboard, then opens the App Store.

Call once at launch:

```swift theme={null}
func application(
    _ application: UIApplication,
    didFinishLaunchingWithOptions launchOptions: [UIApplication.LaunchOptionsKey: Any]? = nil
) -> Bool {
    DynamicLinks.configure(apiKey: "dlk_sdk_…")
    DynamicLinks.shared.dynamicLinkHosts = ["yourbrand.dshl.in"]
    DynamicLinks.shared.performDeferredCheckIfNeeded { link, error in
        // navigate if link?.appUrl != nil
    }
    return true
}
```

On **first open after install** the SDK:

1. Reads `UIPasteboard.general` if `DashlinkPasteboardRetrievalEnabled` is not `NO`.
2. Accepts the value only when it looks like this app's Dynamic Link host.
3. JSON-resolves with `deferred=1`, `match=pasteboard`, and the recovered `click_id`.
4. Returns `PendingDynamicLink` (`appUrl`, UTMs, `isDeferred=true`, `clickId`).
5. **Clears** the pasteboard value and marks deferred consumed (`UserDefaults` key `ai.dashlink.sdk.deferredChecked`) so a later launch does not re-fire.

If a Universal Link is already in hand (installed tap), handle that path and skip thinking of it as deferred.

A 401 on JSON resolve means the key is missing, not a Dynamic Link key, revoked, or bound to another organization — no `deferred_open` is published.

### Paste banner (iOS 14+)

Reading the pasteboard can show the system Allow Paste banner once. That is expected iOS behavior. Users who deny paste cannot recover the pending link; the SDK reports a miss and still consumes the check.

Disable with Info.plist:

```xml theme={null}
<key>DashlinkPasteboardRetrievalEnabled</key>
<false/>
```

Default is YES. Turning this off means deferred cannot run.

### Misses

Empty pasteboard, foreign text, or a URL that is not this app's Dynamic Link host is a miss. Deferred is still marked consumed. There is no silent home-screen drop that looks like success.

Clearing app data re-runs recovery. Reinstall is a new container, so first open after reinstall checks again.

Recovery uses the pasteboard value only. If the interstitial never copied the short URL, or the user overwrote the clipboard, there is no destination to recover.

## Tracking

The store interstitial / App Store hop is the **click**. SDK JSON resolve is an **outcome on that click** when `click_id` matches, not a second campaign click.

| Event | When | Join |
| - | - | - |
| `store_redirect` / `app_attempt` | Browser path, app missing | Edge mints `click_id`, puts `dl_cid` on the clipboard URL |
| `deferred_open` | First open, pasteboard recovered | Same `click_id` |
| `deferred_miss` | First open, nothing recoverable | First-open only; no join if there was no URL |
| `app_open` | Installed tap, JSON resolve | New `click_id` |

Campaign totals should unique-count by `click_id`. Do not add `deferred_open` to click volume. Replay of the same `click_id` still returns `app_url` but does not publish a second `deferred_open`.

## Test on a device

Simulators do not exercise Universal Link association the way a real device does.

**1. Delete the app**

So the next tap takes the store path, and iOS will refetch the association file on reinstall.

**2. Tap a staging Dynamic Link**

The interstitial copies the short URL and `dl_cid`, then opens the App Store.

**3. Install a build that includes the SDK**

Associated Domains must list the Dynamic Link host.

**4. Open once**

First open may show a paste banner. After allowing, the app must land on `appUrl`. Analytics must show `deferred_open` for the same `click_id` as the store tap.

If an installed tap still opens Safari, the problem is almost always [app association](https://docs.dashlink.ai/guides/app-dynamic-links/app-association.md), not the SDK.

## Sample and changelog

The [sample app](https://github.com/Dashlink-ai/dashlink-ios/tree/main/Sample) documents the live-tap and deferred acceptance path. Release notes live in the [changelog](https://github.com/Dashlink-ai/dashlink-ios/blob/main/CHANGELOG.md).


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.