Skip to main content

Module 11 — Reference

API surface, troubleshooting, and a final checklist. Unless noted, methods are on the shared singleton PaylisherSDK.shared.

API reference

Setup & handlers

Method	What it does
`onDeepLink(_ handler: (PaylisherDeepLink, Bool) -> Void)`	Registers a closure for received deep links. The `Bool` is `requiresAuth`. No protocol needed.
`onDeepLinkRequiresAuth(_ handler: (PaylisherDeepLink, @escaping (Bool) -> Void) -> Void)`	Registers a closure for auth-gated destinations. Call the completion with `true`/`false`.
`onDeepLinkFailed(_ handler: (URL, Error?) -> Void)`	Registers a closure for parse/handle failures.
`setDeepLinkHandler(_ handler: PaylisherDeepLinkHandler)`	Delegate-based alternative to the closures above.

Forwarding links

Method	What it does
`View.paylisherDeepLinks()`	SwiftUI modifier — forwards `onOpenURL` + `onContinueUserActivity`. iOS 14+.
`handleDeepLink(_ url: URL) -> Bool`	Handles a custom-scheme URL. Returns `true` if handled.
`handleUserActivity(_ userActivity: NSUserActivity) -> Bool`	Handles a Universal Link `NSUserActivity`.
`handleURLContexts(_ contexts: Set<UIOpenURLContext>)`	Handles URLs from `SceneDelegate`.

Pending (auth) & deferred

Method	What it does
`completePendingDeepLink()`	Completes a pending auth-gated link after successful login.
`cancelPendingDeepLink()`	Cancels a pending link (emits a `Deep Link Cancelled` event).
`checkDeferredDeepLink(onSuccess:onNoMatch:onError:)`	Checks for a deferred (install-attribution) deep link on first launch.

See also: the PaylisherDeepLink object and config table (Module 5) and PaylisherDeepLinkConfig (Module 3).

Troubleshooting

Symptom	Cause / fix
Custom scheme does nothing	Scheme not declared in Info.plist → CFBundleURLTypes, or `customSchemes` doesn't include it.
Universal Link opens Safari instead of the app	The `apple-app-site-association` for your domain doesn't yet list your `appID`. Send your Team ID + Bundle ID to Paylisher. iOS caches the file — delete and reinstall to refresh.
`onDeepLink` never fires	You didn't add `paylisherDeepLinks()` (SwiftUI) or the `AppDelegate`/`SceneDelegate` forwarders (UIKit).
Opens, but lands on Home	The link's path word doesn't match a `case` in `parseTarget`. Compare the `[PaylisherDeepLink] Handling URL` log against your router.
The same link is handled twice	In UIKit, don't also process `launchOptions[.url]` — `open:` already fires on cold launch.
Auth-gate doesn't resume after login	Ensure `setAuthenticated(true)` (or `completePendingDeepLink()`) is called on login success.
Events don't carry `campaign_key`	The link had no campaign key, or `autoRegisterCampaignKeys` is `false`. Attribution is also session-scoped — absent in organic sessions.
Deferred link never matches	Deferred not enabled, the app launched offline on first run, or the attribution window elapsed.

Integration checklist

You've reached the end of the iOS track. Back to the overview or the module map.

API reference
Troubleshooting
Integration checklist