Deep Links (iOS)

This guide is split into focused, ordered modules. Each one does a single job, so you can follow them top to bottom — or jump straight to the part you need.

New to Paylisher deep linking? Read the platform-neutral Deep Linking — Overview first. It explains the link types, the four-layer mental model, pathSegments, and attribution — the concepts every module below builds on.

This track targets Paylisher iOS 1.8.4 or later (iOS 13+). For Android, see the Android track.

---

What you'll build

Paylisher receives an incoming link, resolves its campaign data, stamps attribution onto your analytics events, and hands you a parsed object so you can navigate the user to the right screen. You write only two things: one line to forward the link, and a small router.

Link type	Example	When it fires
Custom scheme	yourapp://products/42	App installed; opened from another app, web, or a notification.
Universal Link	https://link.paylisher.com/c/AbC123	App installed; opened from Safari/email/social — no "Open in app?" prompt.
Deferred deep link	(resolved on first launch)	App was not installed when tapped; destination delivered after install.

---

The modules

Follow these in order. Modules 2–5 are the core integration; the rest you add when you need them.

#	Module	What you do
2	Prerequisites	Declare your custom scheme in Info.plist and add Associated Domains for Universal Links.
3	SDK setup	Set deepLinkConfig, call setup(), and register your handlers.
4	Forwarding links	Hand OS links to the SDK — SwiftUI one-liner, UIKit, or SceneDelegate (iOS 13).
5	Routing ⭐	Turn the parsed link into navigation — pick the tab, push the nested screen.
6	Auth-gated destinations	Gate screens behind login (e.g. wallet).
7	Deferred deep links	Recover the destination on the first launch after install.
8	Attribution & source	Campaign keys, jid, and the canonical campaign_source — all automatic.
9	Creating links	Build dashboard links whose target path matches your routes.
10	Testing	Fire links with xcrun simctl openurl and verify the right screen opens.
11	Reference	API, the PaylisherDeepLink object, troubleshooting, and a checklist.

---

The shortest possible integration

If you just want to see a link work, here is the whole core in one place. Each piece is explained in its module.

import Paylisher

// Module 3 — configure & set up
let config = PaylisherConfig(apiKey: "phc_YOUR_PROJECT_KEY", host: "https://us.i.paylisher.com")
let deepLinkConfig = PaylisherDeepLinkConfig()
deepLinkConfig.customSchemes = ["yourapp"]
deepLinkConfig.universalLinkDomains = ["link.paylisher.com"]
config.deepLinkConfig = deepLinkConfig
PaylisherSDK.shared.setup(config)

// Module 5 — route the parsed link to a screen
PaylisherSDK.shared.onDeepLink { deepLink, requiresAuth in
    guard !requiresAuth else { return }
    DeepLinkRouter.shared.navigate(deepLink)
}

// Module 4 — forward OS links (SwiftUI: one modifier on your root view)
ContentView().paylisherDeepLinks()

Start with Prerequisites →