Module 3 — SDK setup

Configure deep links on your PaylisherConfig, call setup() once, and register the handlers that receive parsed links. setup() initializes the deep-link manager automatically — there is no separate initialize() call.

---

1. Configure & set up

Set config.deepLinkConfig before setup(). A good place is your App init or AppDelegate.

import Paylisher

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"]
deepLinkConfig.authRequiredDestinations = ["wallet", "account"]   // optional — see Module 6
deepLinkConfig.debugLogging             = true                    // during integration
config.deepLinkConfig = deepLinkConfig

PaylisherSDK.shared.setup(config)

customSchemes / universalLinkDomains here are informational; what actually routes a URL to your app is the OS-level config in Module 2. Fill them in anyway for clarity.

---

2. Register your handlers

Register one or more closures on PaylisherSDK.shared — no protocol to implement. Do this right after setup().

// Called for every received deep link.
PaylisherSDK.shared.onDeepLink { deepLink, requiresAuth in
    // requiresAuth == true → destination is auth-gated; don't navigate yet (see Module 6).
    if !requiresAuth {
        DeepLinkRouter.shared.navigate(deepLink)   // your router — see Module 5
    }
}

// Optional: called when an auth-gated destination needs a logged-in user (Module 6).
PaylisherSDK.shared.onDeepLinkRequiresAuth { deepLink, complete in
    if isUserLoggedIn { complete(true) } else { showLogin { success in complete(success) } }
}

// Optional: called when a link can't be parsed/handled.
PaylisherSDK.shared.onDeepLinkFailed { url, error in
    print("Deep link failed: \(url) — \(error?.localizedDescription ?? "unknown")")
}

Handler	When it's called	What to do
onDeepLink	A link was received & parsed	Hand it to your router → navigate
onDeepLinkRequiresAuth	Destination needs login	Start your login flow; report the result to complete
onDeepLinkFailed	A link couldn't be parsed	(Optional) log it

---

Configuration reference — PaylisherDeepLinkConfig

Property	Type	Default	Description
customSchemes	[String]	[]	Custom URL schemes you handle, e.g. ["yourapp"].
universalLinkDomains	[String]	[]	Domains handled as Universal Links.
authRequiredDestinations	[String]	[]	Destinations requiring an authenticated user (see Module 6).
autoRegisterCampaignKeys	Bool	true	Auto-register campaign_key + deeplink_key for the session (see Module 8).
captureDeepLinkEvents	Bool	true	Emit the Deep Link Opened business event (plus Completed / Cancelled for auth-gated links).
captureDeepLinkDiagnostics	Bool	false	Also emit verbose diagnostic / funnel events (deeplink_received, deeplink_resolved, …) for debugging. Off by default to keep your event stream clean.
autoHandleDeepLinks	Bool	true	Process links automatically on arrival.
debugLogging	Bool	false	Verbose [PaylisherDeepLink] logs (use in debug builds).
pendingDeepLinkTimeout	TimeInterval	300	How long an auth-gated link waits for login before expiring (seconds).

---

Delegate alternative

Prefer a delegate over closures? Implement PaylisherDeepLinkHandler and register it with setDeepLinkHandler(_:):

extension AppDelegate: PaylisherDeepLinkHandler {
    func paylisherDidReceiveDeepLink(_ deepLink: PaylisherDeepLink, requiresAuth: Bool) { /* … */ }
    func paylisherDeepLinkRequiresAuth(_ deepLink: PaylisherDeepLink, completion: @escaping (Bool) -> Void) { /* … */ }
    func paylisherDeepLinkDidFail(_ url: URL, error: Error?) { /* … */ }
}

PaylisherSDK.shared.setDeepLinkHandler(self)

Next: Module 4 — Forwarding links →