Deep Links (iOS)

Deep Links (iOS)

Deep linking is required for Games You Play (GYP) and optional but recommended for Sports You Watch (SYW) and Tournaments. Deeplinks allow Lucra to route users directly into matchups, onboarding, verification flows, and shared matchup invitations.

---

🔗 Overview

Lucra uses a two-step deep linking integration:

1. Lucra → Your App Lucra generates an internal deep link (Lucra URL) and asks your app to turn it into a shareable link (your domain, shortened link, QR code, etc.).

2. Your App → Lucra When a user opens your shared link, your app unpacks it and hands the original Lucra URL back into the SDK, which returns the correct LucraFlow to present.

---

📌 Step 1 — Register a Deep Link Provider

You must register handleMatchupInviteDeeplink from the LucraClient to receive the matchupId when a user shares the matchup. Use this to construct a shareable URL that routes to your app.

lucraClient.handleMatchupInviteDeeplink { matchupId in
    // Your URL shortener, FireBase Dynamic Link, custom domain, etc.
    await MyDeeplinkService().createShortLink(from: lucraUrl)
}

This is an async function, meaning your shortener service can perform network calls.

---

📌 Step 2 — Handling Incoming Deep Links

When your app receives a shared link (custom URL scheme, universal link, or QR code), you must decode the matchupId from the URL and feed it to the SDK:

func handleIncomingLink(_ url: URL) {
    MyDeeplinkService().unpack(url) { matchupId in
        if let flow = lucraClient.handleMatchupInviteDeeplink(matchupId: matchupId) {
            currentLucraFlow = flow
        } else {
            print("Not a Lucra link")
        }
    }
}

If handleDeeplink returns a LucraFlow, your app should present it immediately.

---

📱 Universal Links & QR Codes

Universal Links

Implement in SceneDelegate or SwiftUI .onOpenURL:

.onOpenURL { url in
    handleIncomingLink(url)
}

QR Codes

Handle via:

.onContinueUserActivity(NSUserActivityTypeBrowsingWeb) { activity in
    guard let url = activity.webpageURL else { return }
    handleIncomingLink(url)
}

This enables scanning Lucra QR invitations.

---

🧭 Push Notifications

The LucraSDK can also emit push notifications for deeplinking to specific flows.

See Push Notifications for details.

---

🧪 Testing Deep Links

1. Generate a Lucra deep link by creating a matchup.

2. Ensure your link shortener returns a public URL.

3. Tap the link on your device:

   • App should open

   • lucraClient.handleDeeplink(url:) should return a non-nil LucraFlow

   • The flow should immediately present full screen

---

✔️ Integration Checklist

• Implement and register a deeplinkProvider

• Implement a URL shortener (or pass-through handler)

• Handle universal links and custom URL schemes

• Pass unpacked Lucra URLs into handleDeeplink(url:)

• Present the returned LucraFlow

Your deep linking integration is now complete.