Mastering Deep Linking & Universal Links in Rork Max — Deferred Deep Links, Attribution & Growth

// URL Scheme definition
enum DeepLinkScheme {
    case native(NativeDeepLink)
    case web(WebDeepLink)
    case attributionTracking(AttributionData)
 
    static func parse(_ url: URL) -> DeepLinkScheme? {
        if url.scheme == "myapp" {
            return parseNativeDeepLink(url)
        } else if url.host == "myapp.com" {
            return parseWebDeepLink(url)
        }
        return nil
    }
 
    private static func parseNativeDeepLink(_ url: URL) -> DeepLinkScheme? {
        let components = URLComponents(url: url, resolvingAgainstBaseURL: true)
        guard let host = components?.host else { return nil }
 
        switch host {
        case "product":
            if let productId = components?.queryItems?.first(where: { $0.name == "id" })?.value {
                return .native(.product(id: productId))
            }
        case "user":
            if let username = components?.queryItems?.first(where: { $0.name == "username" })?.value {
                return .native(.user(username: username))
            }
        case "invite":
            if let inviteCode = components?.queryItems?.first(where: { $0.name == "code" })?.value {
                return .native(.invite(code: inviteCode))
            }
        default:
            return nil
        }
        return nil
    }
}
 
enum NativeDeepLink {
    case product(id: String)
    case user(username: String)
    case invite(code: String)
    case home
}
 
enum WebDeepLink {
    case product(slug: String)
    case article(slug: String)
    case profile(username: String)
}
 
// Deep link navigation handler
@main
struct MyApp: App {
    @StateObject private var deepLinkRouter = DeepLinkRouter()
 
    var body: some Scene {
        WindowGroup {
            ContentView()
                .environmentObject(deepLinkRouter)
                .onOpenURL { url in
                    handleDeepLink(url)
                }
                .onContinueUserActivity(NSUserActivityTypeBrowsingWeb) { userActivity in
                    if let url = userActivity.webpageURL {
                        handleDeepLink(url)
                    }
                }
        }
    }
 
    private func handleDeepLink(_ url: URL) {
        // Parse and route the deep link
        if let scheme = DeepLinkScheme.parse(url) {
            deepLinkRouter.navigate(to: scheme)
        }
    }
}

// Step 1: Create apple-app-site-association file
// Place at: https://yourdomain.com/.well-known/apple-app-site-association
 
{
  "applinks": {
    "apps": [],
    "details": [
      {
        "appID": "com.example.myapp",
        "paths": [
          "/products/*",
          "/users/*",
          "/articles/*"
        ]
      }
    ]
  },
  "webcredentials": {
    "apps": ["com.example.myapp"]
  }
}
 
// Step 2: Configure entitlements in Rork Max
// Request this in your prompt:
// "Add associated domains entitlement for universal links:
//  yourdomain.com, www.yourdomain.com"
 
// Step 3: Handle universal links in SwiftUI
class UniversalLinkHandler {
    func parseUniversalLink(_ url: URL) -> DeepLinkScheme? {
        // Remove trailing slashes for consistent parsing
        var urlPath = url.path
        while urlPath.hasSuffix("/") {
            urlPath.removeLast()
        }
 
        // Match against your route patterns
        if urlPath.starts(with: "/products/") {
            let productSlug = String(urlPath.dropFirst("/products/".count))
            return .native(.product(id: productSlug))
        }
 
        if urlPath.starts(with: "/users/") {
            let username = String(urlPath.dropFirst("/users/".count))
            return .native(.user(username: username))
        }
 
        if urlPath.starts(with: "/articles/") {
            let articleSlug = String(urlPath.dropFirst("/articles/".count))
            // You might need to fetch the article ID from the slug
            return .native(.article(slug: articleSlug))
        }
 
        return nil
    }
}

class UniversalLinkRouter {
    let deepLinkHandler = UniversalLinkHandler()
 
    func handleUniversalLink(_ url: URL) {
        // Some paths should always open in browser
        let webOnlyPaths = ["/legal/", "/privacy/", "/terms/"]
 
        let pathMatches = webOnlyPaths.contains { path in
            url.path.starts(with: path)
        }
 
        if pathMatches {
            // Open in browser
            UIApplication.shared.open(url)
            return
        }
 
        // Try to route in app
        if let deepLink = deepLinkHandler.parseUniversalLink(url) {
            navigateTo(deepLink)
        } else {
            // Fall back to browser
            UIApplication.shared.open(url)
        }
    }
 
    private func navigateTo(_ deepLink: DeepLinkScheme) {
        // Navigation implementation
    }
}

// For Rork Max apps targeting Android, request this configuration:
// "Add App Links configuration for Android with the following domains:
//  yourdomain.com, www.yourdomain.com
//  Asset link at: https://yourdomain.com/.well-known/assetlinks.json"
 
// assetlinks.json configuration:
[
  {
    "relation": ["delegate_permission/common.handle_all_urls"],
    "target": {
      "namespace": "android_app",
      "package_name": "com.example.myapp",
      "sha256_cert_fingerprints": [
        "AA:BB:CC:DD:EE:FF:00:11:22:33:44:55:66:77:88:99:AA:BB:CC:DD:EE:FF:00:11:22:33:44:55:66:77:88:99"
      ]
    }
  }
]

// Deferred deep link service with attribution tracking
class DeferredDeepLinkService {
    private let apiBaseURL = URL(string: "https://api.yourdomain.com")!
    private let deviceIdentifier = UIDevice.current.identifierForVendor?.uuidString ?? UUID().uuidString
 
    // Store deferred deep link on first app launch
    func fetchDeferredDeepLink() async throws -> DeferredDeepLinkData? {
        var request = URLRequest(url: apiBaseURL.appendingPathComponent("/deferred-links/fetch"))
        request.httpMethod = "POST"
 
        let payload = DeferredLinkRequest(
            deviceId: deviceIdentifier,
            appVersion: Bundle.main.appVersion,
            osVersion: UIDevice.current.systemVersion,
            isFirstLaunch: !UserDefaults.standard.bool(forKey: "hasLaunchedBefore")
        )
 
        request.setValue("application/json", forHTTPHeaderField: "Content-Type")
        request.httpBody = try JSONEncoder().encode(payload)
 
        let (data, _) = try await URLSession.shared.data(for: request)
        let decoder = JSONDecoder()
        let response = try decoder.decode(DeferredLinkResponse.self, from: data)
 
        return response.deepLinkData
    }
 
    // Log attribution data
    func logAttribution(source: String, campaign: String, medium: String) async throws {
        var request = URLRequest(url: apiBaseURL.appendingPathComponent("/attribution"))
        request.httpMethod = "POST"
 
        let attribution = AttributionEvent(
            deviceId: deviceIdentifier,
            source: source,
            campaign: campaign,
            medium: medium,
            timestamp: Date()
        )
 
        request.setValue("application/json", forHTTPHeaderField: "Content-Type")
        request.httpBody = try JSONEncoder().encode(attribution)
 
        _ = try await URLSession.shared.data(for: request)
    }
}
 
struct DeferredLinkRequest: Codable {
    let deviceId: String
    let appVersion: String
    let osVersion: String
    let isFirstLaunch: Bool
}
 
struct DeferredDeepLinkData: Codable {
    let deepLink: String
    let source: String // "referral", "ad_campaign", etc.
    let campaign: String
    let userId: String? // ID of user who shared the link
}
 
struct AttributionEvent: Codable {
    let deviceId: String
    let source: String
    let campaign: String
    let medium: String
    let timestamp: Date
}

class AppStartupManager {
    @StateObject private var deferredLinkService = DeferredDeepLinkService()
 
    func setupAppLaunchFlow() async {
        // Mark that app has launched
        if !UserDefaults.standard.bool(forKey: "hasLaunchedBefore") {
            UserDefaults.standard.set(true, forKey: "hasLaunchedBefore")
 
            // Fetch deferred deep link on first launch
            do {
                if let deferredLink = try await deferredLinkService.fetchDeferredDeepLink() {
                    // Log the attribution
                    try await deferredLinkService.logAttribution(
                        source: deferredLink.source,
                        campaign: deferredLink.campaign,
                        medium: "deferred_deep_link"
                    )
 
                    // Route to the deep link
                    handleDeepLinkString(deferredLink.deepLink)
 
                    // Optional: Store the referral relationship
                    if let referrerId = deferredLink.userId {
                        UserDefaults.standard.set(referrerId, forKey: "referredBy")
                    }
                }
            } catch {
                // Log error but don't block app startup
                print("Failed to fetch deferred deep link: \(error)")
            }
        }
    }
 
    private func handleDeepLinkString(_ deepLinkString: String) {
        guard let url = URL(string: deepLinkString) else { return }
        if let scheme = DeepLinkScheme.parse(url) {
            // Navigate to the appropriate screen
            navigateToDeepLink(scheme)
        }
    }
}

class AttributionTracker {
    struct Campaign {
        let id: String
        let source: String // "organic", "paid_social", "email", "referral"
        let medium: String // "cpc", "display", "email", "organic"
        let name: String
        let content: String?
    }
 
    enum EventType: String, Codable {
        case appInstall = "app_install"
        case appOpen = "app_open"
        case productView = "product_view"
        case addToCart = "add_to_cart"
        case purchase = "purchase"
        case share = "share"
        case signup = "signup"
    }
 
    private let apiURL = URL(string: "https://api.yourdomain.com")!
 
    // Log conversion event with attribution data
    func logEvent(
        _ eventType: EventType,
        userId: String?,
        metadata: [String: Any]? = nil,
        campaign: Campaign? = nil
    ) async throws {
        var request = URLRequest(url: apiURL.appendingPathComponent("/events"))
        request.httpMethod = "POST"
 
        let event = ConversionEvent(
            eventId: UUID().uuidString,
            timestamp: Date(),
            eventType: eventType.rawValue,
            userId: userId,
            deviceId: UIDevice.current.identifierForVendor?.uuidString ?? "",
            campaign: campaign != nil ? CampaignData(
                id: campaign!.id,
                source: campaign!.source,
                medium: campaign!.medium,
                name: campaign!.name,
                content: campaign!.content
            ) : nil,
            metadata: metadata
        )
 
        request.setValue("application/json", forHTTPHeaderField: "Content-Type")
        request.httpBody = try JSONEncoder().encode(event)
 
        _ = try await URLSession.shared.data(for: request)
    }
 
    // Track referral signups
    func trackReferral(
        referrerId: String,
        refereeId: String,
        reward: Double
    ) async throws {
        var request = URLRequest(url: apiURL.appendingPathComponent("/referrals"))
        request.httpMethod = "POST"
 
        let referral = ReferralEvent(
            referrerId: referrerId,
            refereeId: refereeId,
            timestamp: Date(),
            reward: reward
        )
 
        request.setValue("application/json", forHTTPHeaderField: "Content-Type")
        request.httpBody = try JSONEncoder().encode(referral)
 
        _ = try await URLSession.shared.data(for: request)
    }
}
 
struct ConversionEvent: Codable {
    let eventId: String
    let timestamp: Date
    let eventType: String
    let userId: String?
    let deviceId: String
    let campaign: CampaignData?
    let metadata: [String: AnyCodable]?
}
 
struct CampaignData: Codable {
    let id: String
    let source: String
    let medium: String
    let name: String
    let content: String?
}
 
struct ReferralEvent: Codable {
    let referrerId: String
    let refereeId: String
    let timestamp: Date
    let reward: Double
}

class UTMParameterParser {
    struct UTMParameters: Codable {
        let source: String?      // utm_source
        let medium: String?      // utm_medium
        let campaign: String?    // utm_campaign
        let content: String?     // utm_content
        let term: String?        // utm_term
    }
 
    static func extractUTM(from url: URL) -> UTMParameters {
        let components = URLComponents(url: url, resolvingAgainstBaseURL: true)
        let queryItems = components?.queryItems ?? []
 
        return UTMParameters(
            source: queryItems.first(where: { $0.name == "utm_source" })?.value,
            medium: queryItems.first(where: { $0.name == "utm_medium" })?.value,
            campaign: queryItems.first(where: { $0.name == "utm_campaign" })?.value,
            content: queryItems.first(where: { $0.name == "utm_content" })?.value,
            term: queryItems.first(where: { $0.name == "utm_term" })?.value
        )
    }
 
    static func createDeepLinkWithUTM(
        baseDeepLink: String,
        utm: UTMParameters
    ) -> String? {
        guard var components = URLComponents(string: baseDeepLink) else {
            return nil
        }
 
        var queryItems = components.queryItems ?? []
 
        if let source = utm.source {
            queryItems.append(URLQueryItem(name: "utm_source", value: source))
        }
        if let medium = utm.medium {
            queryItems.append(URLQueryItem(name: "utm_medium", value: medium))
        }
        if let campaign = utm.campaign {
            queryItems.append(URLQueryItem(name: "utm_campaign", value: campaign))
        }
        if let content = utm.content {
            queryItems.append(URLQueryItem(name: "utm_content", value: content))
        }
        if let term = utm.term {
            queryItems.append(URLQueryItem(name: "utm_term", value: term))
        }
 
        components.queryItems = queryItems
        return components.url?.absoluteString
    }
}

class ReferralProgram {
    let baseDeepLinkURL = "myapp://invite"
 
    func generateReferralLink(for userId: String, withReward reward: Double) -> URL? {
        let referralCode = generateCode(userId: userId, reward: reward)
 
        var components = URLComponents(string: baseDeepLinkURL)
        components?.queryItems = [
            URLQueryItem(name: "code", value: referralCode),
            URLQueryItem(name: "referrer_id", value: userId)
        ]
 
        return components?.url
    }
 
    // Also generate a universal link version
    func generateUniversalReferralLink(for userId: String, withReward reward: Double) -> URL? {
        let referralCode = generateCode(userId: userId, reward: reward)
 
        var components = URLComponents(string: "https://myapp.com/invite")
        components?.queryItems = [
            URLQueryItem(name: "code", value: referralCode),
            URLQueryItem(name: "referrer_id", value: userId)
        ]
 
        return components?.url
    }
 
    private func generateCode(userId: String, reward: Double) -> String {
        let timestamp = Int(Date().timeIntervalSince1970)
        let data = "\(userId):\(timestamp):\(reward)"
        return data.base64Encoded()
    }
}

class ReferralRewardService {
    private let apiURL = URL(string: "https://api.yourdomain.com")!
 
    // Validate referral code and reward both parties
    func processReferral(
        code: String,
        refereeId: String
    ) async throws -> ReferralResult {
        var request = URLRequest(url: apiURL.appendingPathComponent("/referrals/validate"))
        request.httpMethod = "POST"
 
        let payload = ReferralValidation(code: code, refereeId: refereeId)
        request.setValue("application/json", forHTTPHeaderField: "Content-Type")
        request.httpBody = try JSONEncoder().encode(payload)
 
        let (data, response) = try await URLSession.shared.data(for: request)
 
        guard let httpResponse = response as? HTTPURLResponse,
              httpResponse.statusCode == 200 else {
            throw ReferralError.invalidCode
        }
 
        let result = try JSONDecoder().decode(ReferralResult.self, from: data)
        return result
    }
}
 
struct ReferralValidation: Codable {
    let code: String
    let refereeId: String
}
 
struct ReferralResult: Codable {
    let referrerId: String
    let refereeReward: Double
    let referrerReward: Double
    let referrerBalance: Double
}
 
enum ReferralError: Error {
    case invalidCode
    case alreadyUsed
    case expired
}

class DeepLinkTestSuite {
    let app = XCUIApplication()
 
    // Test basic deep link handling
    func testProductDeepLink() throws {
        let deepLink = "myapp://product?id=12345"
        guard let url = URL(string: deepLink) else {
            XCTFail("Invalid URL")
            return
        }
 
        app.open(url)
        app.wait(for: .runningForeground, timeout: 5)
 
        // Verify product screen is displayed
        XCTAssertTrue(app.staticTexts["product-title"].exists)
        XCTAssertTrue(app.staticTexts["product-id-12345"].exists)
    }
 
    // Test universal link fallback
    func testUniversalLinkFallback() {
        let universalLink = "https://myapp.com/products/slug"
        guard let url = URL(string: universalLink) else {
            XCTFail("Invalid URL")
            return
        }
 
        // If app not installed, should open in browser
        // If app installed, should open in app
        let canOpenURL = UIApplication.shared.canOpenURL(url)
        print("Can open URL: \(canOpenURL)")
    }
 
    // Test deferred deep link on first launch
    func testDeferredDeepLink() async throws {
        // Simulate first app launch
        UserDefaults.standard.removeObject(forKey: "hasLaunchedBefore")
 
        let mockDeferredLink = DeferredDeepLinkData(
            deepLink: "myapp://product?id=99999",
            source: "referral",
            campaign: "invite_friends",
            userId: "user123"
        )
 
        // Mock the API response
        // Verify app navigates to the correct screen
    }
 
    // Test referral link generation and validation
    func testReferralFlow() async throws {
        let referralProgram = ReferralProgram()
        let userId = "user123"
        let reward = 10.0
 
        // Generate referral link
        let referralLink = referralProgram.generateReferralLink(for: userId, withReward: reward)
        XCTAssertNotNil(referralLink)
 
        // Verify link format
        let urlString = referralLink?.absoluteString ?? ""
        XCTAssertTrue(urlString.contains("code="))
        XCTAssertTrue(urlString.contains("referrer_id=\(userId)"))
    }
}

class DeepLinkDebugger {
    // Log all deep link navigation for debugging
    func logDeepLink(_ url: URL, isSuccessful: Bool) {
        let log = DeepLinkLog(
            url: url.absoluteString,
            timestamp: Date(),
            isSuccessful: isSuccessful,
            screenRoute: nil
        )
 
        // Save to UserDefaults for inspection
        var logs = UserDefaults.standard.array(forKey: "deep_link_logs") as? [String] ?? []
        logs.append(log.description)
        UserDefaults.standard.set(logs, forKey: "deep_link_logs")
 
        // Print for console debugging
        print("🔗 Deep Link: \(url.absoluteString) - \(isSuccessful ? "✓" : "✗")")
    }
 
    // Display debug UI with recent deep links
    func presentDebugMenu() {
        let logs = UserDefaults.standard.array(forKey: "deep_link_logs") as? [String] ?? []
        print("Recent Deep Links:")
        logs.forEach { print("  \($0)") }
    }
}
 
struct DeepLinkLog {
    let url: String
    let timestamp: Date
    let isSuccessful: Bool
    let screenRoute: String?
 
    var description: String {
        "[\(timestamp.formatted())] \(url) - \(isSuccessful ? "Success" : "Failed")"
    }
}

class SecureDeepLinkValidator {
    private let validHosts = ["myapp.com", "www.myapp.com"]
 
    func validateDeepLink(_ url: URL) -> Bool {
        // Only accept HTTPS for web links
        if let scheme = url.scheme, scheme != "https" {
            return false
        }
 
        // Validate host
        if let host = url.host {
            guard validHosts.contains(host) else { return false }
        }
 
        // Validate URL structure
        let components = URLComponents(url: url, resolvingAgainstBaseURL: true)
        guard let path = components?.path else { return false }
 
        // Whitelist valid paths
        let validPaths = ["/products", "/users", "/articles", "/invite"]
        let isValidPath = validPaths.contains { path.starts(with: $0) }
 
        return isValidPath
    }
 
    // Validate referral codes cryptographically
    func validateReferralCode(_ code: String) -> Bool {
        // Verify HMAC signature
        guard let decodedCode = Data(base64Encoded: code) else { return false }
 
        let signature = decodedCode.prefix(32)
        let payload = decodedCode.suffix(from: 32)
 
        let expectedSignature = HMAC(
            key: "your-secret-key".data(using: .utf8)!,
            data: payload,
            algorithm: .sha256
        ).digest
 
        return signature == expectedSignature
    }
}

// Rork Max generated code + fallback detection
func application(_ application: UIApplication,
                 continue userActivity: NSUserActivity,
                 restorationHandler: @escaping ([UIUserActivityRestoring]?) -> Void) -> Bool {
    guard userActivity.activityType == NSUserActivityTypeBrowsingWeb,
          let url = userActivity.webpageURL else { return false }
 
    // ① Lightweight HEAD self-check on AASA (invisible to user)
    Task.detached(priority: .background) {
        let head = URLRequest(url: URL(string: "https://yourdomain.com/.well-known/apple-app-site-association")!,
                              cachePolicy: .reloadIgnoringLocalCacheData)
        if let (_, response) = try? await URLSession.shared.data(for: head),
           let http = response as? HTTPURLResponse, http.statusCode != 200 {
            Analytics.logEvent("aasa_stale", parameters: ["url": url.absoluteString])
        }
    }
 
    return handleDeepLink(url)
}

<script>
(function() {
  const isInAppBrowser = /FBAN|FBAV|Instagram|Line|Twitter|MicroMessenger|WeChat/i.test(navigator.userAgent);
  const fallback = setTimeout(() => {
    window.location.href = "https://apps.apple.com/app/idXXXXXXXX";
  }, 1500);
 
  // Try universal link first
  window.location.href = "https://yourdomain.com/open?path=" + encodeURIComponent(window.location.pathname);
 
  // If we detect an in-app browser, also try the custom scheme
  if (isInAppBrowser) {
    setTimeout(() => {
      window.location.href = "myapp://" + window.location.pathname.replace(/^\//, "");
    }, 100);
  }
})();
</script>

# .github/workflows/post-release-android.yml
curl -s "https://digitalassetlinks.googleapis.com/v1/statements:list?source.web.site=https://yourdomain.com&relation=delegate_permission/common.handle_all_urls" \
  | jq '.statements[] | select(.target.androidApp.packageName == "com.yourapp")'

// Three-leg fallback. Exactly one leg gets recorded per launch.
enum LinkLeg: String {
    case universal   // ① universal link (recorded in continueUserActivity)
    case scheme      // ② custom scheme
    case store       // ③ store URL
}
 
@MainActor
func openWithFallback(path: String, referral: String?) async {
    var scheme = URLComponents()
    scheme.scheme = "myapp"
    scheme.host = "open"
    scheme.path = path
    scheme.queryItems = referral.map { [URLQueryItem(name: "ref", value: $0)] }
 
    // No canOpenURL. Try it and read the Bool that comes back.
    if let url = scheme.url,
       await UIApplication.shared.open(url, options: [:]) {
        record(.scheme, path: path, hasReferral: referral != nil)
        return
    }
 
    // Even the store hand-off keeps the referral code, so we can recover it later.
    var store = URLComponents(string: "https://apps.apple.com/app/idXXXXXXXX")!
    store.queryItems = [
        URLQueryItem(name: "pt", value: "YOUR_PROVIDER_TOKEN"),
        URLQueryItem(name: "ct", value: referral ?? "organic"),
        URLQueryItem(name: "mt", value: "8"),
    ]
    await UIApplication.shared.open(store.url!, options: [:])
    record(.store, path: path, hasReferral: referral != nil)
}
 
func record(_ leg: LinkLeg, path: String, hasReferral: Bool) {
    Analytics.logEvent("deep_link_opened", parameters: [
        "link_leg": leg.rawValue,
        "path": path,
        "has_referral": hasReferral,
    ])
}

{
  "expo": {
    "ios": {
      "infoPlist": {
        "LSApplicationQueriesSchemes": ["line", "twitter", "instagram"]
      }
    }
  }
}

enum OnboardingMilestone: Int {
    case launched = 0
    case viewedPaywall = 1
    case startedTrial = 2
    case completedOnboarding = 3
    case firstSession2Min = 4
    case secondDayReturn = 5
}
 
func updateConversionValue(for milestone: OnboardingMilestone) {
    // Map to SKAdNetwork 4.0 coarse-grained value as well
    let coarse: SKAdNetwork.CoarseConversionValue = {
        switch milestone {
        case .launched, .viewedPaywall: return .low
        case .startedTrial, .completedOnboarding: return .medium
        case .firstSession2Min, .secondDayReturn: return .high
        }
    }()
 
    SKAdNetwork.updatePostbackConversionValue(milestone.rawValue,
                                              coarseValue: coarse,
                                              lockWindow: false) { error in
        if let error { Crashlytics.crashlytics().record(error: error) }
    }
}