Deep Linking — Overview
Paylisher turns every link you create in the dashboard into a measurable, routable entry point into your app. When a user taps a link, the SDK receives it, resolves its campaign data from the backend, stamps attribution onto your analytics events, and hands you a parsed object so you can navigate the user to the right screen — with almost no code on your side.
This page explains the concepts that are the same on every platform. When you understand it, pick your platform track and follow the modules in order:
- iOS → Deep Link Integration (iOS)
- Android → Deep Link Integration (Android)
The three kinds of links
| Link type | Example | When it fires |
|---|---|---|
| Custom scheme | yourapp://products/42 | App is installed; opened from another app, a web page, or a notification. |
| Universal Link (iOS) / App Link (Android) | https://link.paylisher.com/c/AbC123 | App is installed; opened from the browser, email, or social — verified, no prompt/chooser. |
| Deferred deep link | (resolved on first launch) | App was not installed when the link was tapped; the destination is delivered on the first launch after install. |
Custom schemes and Universal/App Links are two different OS-level mechanisms, but once a link reaches the SDK they are handled identically — your routing code never has to tell them apart.
How it works — the pipeline
A link is tapped
│
▼
The OS hands the link to your app ← Layer 1: OS registration (Info.plist / Manifest + association file)
│
▼
You forward it to the SDK (one line)
│
▼
The SDK parses & normalizes the URL ← Layer 2: SDK (automatic)
→ pathSegments = ["products","42"]
→ resolves the campaign (if a key is present), attaches attribution
│
▼
The SDK calls your handler with a
PaylisherDeepLink object
│
▼
Your router maps pathSegments → a screen ← Layer 3: your routing code
│
▼
The right screen opens ← matches the link you built in the dashboard (Layer 4)
You only write two things: forwarding the link to the SDK (one line) and a small router that turns the parsed link into a screen. Everything in between — parsing, campaign resolution, attribution, journey tracking, cold-start handling — is automatic.
The four layers (the mental model)
A deep link works only when four layers agree on the same words:
| Layer | Where it's defined | Its job |
|---|---|---|
| 1. OS registration | Info.plist + entitlements (iOS) / AndroidManifest.xml (Android) | Decides which URLs open your app. |
| 2. SDK | SDK code (ready-made) | Normalizes the incoming URL into pathSegments. |
| 3. Your router | Your parseTarget / destinationFor | Maps pathSegments → which screen. |
| 4. The dashboard link | When you create the link in Paylisher | The link's target path must use the same words as your router. |
The single most important rule. A deep link either never opens (Layer 1 missing) or it opens but lands on the wrong screen (Layer 3 ↔ Layer 4 mismatch — the path word in the dashboard link differs from the word your router expects). Almost every "broken deep link" is one of these two.
pathSegments — one route format for both platforms
The SDK normalizes every incoming URL into a pathSegments array. The host of a custom scheme and the path of a Universal/App Link collapse into the same segments:
yourapp://products/42/reviews → ["products","42","reviews"]
https://link.paylisher.com/products/42/reviews → ["products","42","reviews"]
Because the result is identical across link types and across iOS/Android, you write your routing logic once per platform against pathSegments — never re-parsing the raw URL. This is why the iOS and Android routers look the same apart from language.
The vocabulary contract
You choose a word for each screen ("path vocabulary"). The same words must appear in two places:
| Screen | Path word | Example link |
|---|---|---|
| Home | home | yourapp://home |
| Product detail | products/<id> | yourapp://products/42 |
| Wallet (needs login) | wallet | yourapp://wallet |
| Profile | profile | yourapp://profile |
These words are identifiers you invent — they can be in any language (urunler/42 works too). The only requirement: your router and the dashboard link must use the same word. Define this vocabulary once and reuse it on both platforms.
Attribution is automatic
When a link carries a campaign key, the SDK attaches attribution to every analytics event in that session — you write nothing:
| Property | Meaning |
|---|---|
campaign_key / deeplink_key | The campaign key of the link that opened the session. |
jid | Journey ID, for cross-event attribution. |
journey_source | How the journey started (e.g. deeplink). |
campaign_source | The canonical traffic source (see below). |
Session-scoped by design. These are attached only to events in the session the link opened. If the app is later opened organically (no deep link), they are not carried over — organic sessions stay clean.
Canonical traffic source
campaign_source is normalized by the SDK into exactly one of seven canonical tokens, identical on iOS, Android, and in the dashboard:
instagram facebook twitter tiktok qr direct unknown
The SDK derives it defensively from utm_source / source, then referrer, then a low-priority platform hint — so even a raw ?source=ig becomes instagram. direct means no source signal at all; unknown means a signal was present but unrecognized. Details in the platform Attribution & source module.
Decide three things before you start
- A custom scheme — e.g.
yourapp→yourapp://...opens your app. - A Universal/App Link domain (recommended) — e.g.
link.paylisher.com. - Your path vocabulary — one word per screen (the table above).
Fastest path to a working link: start with the custom scheme only. Universal/App Links need a server-side association file; the scheme works immediately, and you add verified
https://links afterwards.
Where to go next
Each platform track splits the integration into focused, ordered modules:
| Module | What it covers |
|---|---|
| 1. Overview & module map | Orientation + the integration-steps checklist |
| 2. Prerequisites | Register the scheme + Universal/App Link domain (OS-level) |
| 3. SDK setup | Configure deepLinkConfig, call setup(), register handlers |
| 4. Forwarding links | Hand OS links to the SDK |
| 5. Routing ⭐ | Map pathSegments → screens (the heart of the integration) |
| 6. Auth-gated destinations | Screens that require login |
| 7. Deferred deep links | First-launch (post-install) attribution |
| 8. Attribution & source | Campaign keys, jid, campaign_source |
| 9. Creating links | Build dashboard links that match your routes |
| 10. Testing | Fire links and verify the right screen opens |
| 11. Reference | API, the PaylisherDeepLink object, troubleshooting, checklist |