Skip to main content
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.
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

Without the SDK, a fresh install opens on the home screen and the store tap cannot be joined to first open. See Receive 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:

CocoaPods

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.
configure rejects keys that do not start with dlk_sdk_. 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.
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.
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.

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:
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:
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. 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, not the SDK.

Sample and changelog

The sample app documents the live-tap and deferred acceptance path. Release notes live in the changelog.