Deep Linking

Deep Linking Generator

Generate deep linking infrastructure with URL schemes, Universal Links, and App Intents for Siri/Shortcuts.

When This Skill Activates

• User wants to handle custom URL schemes (myapp://)
• User mentions Universal Links or Associated Domains
• User wants Siri Shortcuts or App Intents
• User needs to navigate to specific content from external sources

Pre-Generation Checks

Before generating, verify:

1. Existing Deep Link Handling

   bashCopy code
   # Check for existing URL handling
   grep -r "onOpenURL\|open.*url\|handleOpen" --include="*.swift" | head -5
   

2. URL Scheme in Info.plist

   bashCopy code
   # Check for CFBundleURLTypes
   find . -name "Info.plist" -exec grep -l "CFBundleURLSchemes" {} \;
   

3. Associated Domains Entitlement

   bashCopy code
   find . -name "*.entitlements" -exec grep -l "associated-domains" {} \;
   

Configuration Questions

1. URL Scheme

• What custom URL scheme? (e.g., myapp)
• This enables myapp://path/to/content links

2. Universal Links

• Yes - Handle HTTPS links (requires AASA file on server)
• No - Custom URL scheme only

3. App Intents / Siri Shortcuts

• Yes - Enable voice commands and Shortcuts app
• No - URL-based deep linking only

4. Link Types

• Profile: /users/{id}
• Content: /items/{id}
• Actions: /actions/share, /actions/create
• Custom routes based on app needs

Generated Files

Core Infrastructure

Copy code
Sources/DeepLinking/
├── DeepLinkRouter.swift       # Central router
├── DeepLink.swift             # Route definitions
└── UniversalLinkHandler.swift # Universal link processing

App Intents (Optional)

Copy code
Sources/AppIntents/
├── OpenContentIntent.swift    # Open specific content
├── AppShortcuts.swift         # Shortcuts provider
└── ContentEntity.swift        # Entities for Spotlight/Siri

Server Files (Universal Links)

Copy code
.well-known/
└── apple-app-site-association  # AASA file template

Key Features

Route Definitions

swiftCopy code
enum DeepLink: Equatable {
    case home
    case profile(userId: String)
    case item(itemId: String)
    case settings
    case action(ActionType)

    enum ActionType {
        case share(itemId: String)
        case create
    }
}

URL Parsing

swiftCopy code
extension DeepLink {
    init?(url: URL) {
        guard let components = URLComponents(url: url, resolvingAgainstBaseURL: true) else {
            return nil
        }

        let pathComponents = components.path.split(separator: "/").map(String.init)

        switch pathComponents {
        case ["users", let userId]:
            self = .profile(userId: userId)
        case ["items", let itemId]:
            self = .item(itemId: itemId)
        case ["settings"]:
            self = .settings
        default:
            self = .home
        }
    }
}

SwiftUI Integration

swiftCopy code
@main
struct MyApp: App {
    @State private var router = DeepLinkRouter()

    var body: some Scene {
        WindowGroup {
            ContentView()
                .environment(router)
                .onOpenURL { url in
                    router.handle(url)
                }
        }
    }
}

App Intents Integration

OpenIntent for Navigation

swiftCopy code
struct OpenItemIntent: OpenIntent {
    static let title: LocalizedStringResource = "Open Item"

    @Parameter(title: "Item")
    var target: ItemEntity

    func perform() async throws -> some IntentResult {
        await router.navigate(to: .item(itemId: target.id))
        return .result()
    }
}

App Shortcuts

swiftCopy code
struct AppShortcuts: AppShortcutsProvider {
    static var appShortcuts: [AppShortcut] {
        AppShortcut(
            intent: OpenItemIntent(),
            phrases: [
                "Open \(\.$target) in \(.applicationName)",
                "Show \(\.$target)"
            ],
            shortTitle: "Open Item",
            systemImageName: "doc"
        )
    }
}

Required Capabilities

URL Scheme (Info.plist)

xmlCopy code
<key>CFBundleURLTypes</key>
<array>
    <dict>
        <key>CFBundleURLSchemes</key>
        <array>
            <string>myapp</string>
        </array>
        <key>CFBundleURLName</key>
        <string>com.yourcompany.myapp</string>
    </dict>
</array>

Universal Links (Entitlements)

xmlCopy code
<key>com.apple.developer.associated-domains</key>
<array>
    <string>applinks:yourapp.com</string>
    <string>applinks:www.yourapp.com</string>
</array>

Server Configuration (AASA)

Host at https://yourapp.com/.well-known/apple-app-site-association:

jsonCopy code
{
  "applinks": {
    "apps": [],
    "details": [
      {
        "appID": "TEAMID.com.yourcompany.yourapp",
        "paths": [
          "/items/*",
          "/users/*",
          "/share/*"
        ]
      }
    ]
  }
}

Integration Steps

1. Basic URL Handling

swiftCopy code
@main
struct MyApp: App {
    var body: some Scene {
        WindowGroup {
            ContentView()
                .onOpenURL { url in
                    handleDeepLink(url)
                }
        }
    }
}

2. Universal Links (UIKit)

swiftCopy code
// In SceneDelegate
func scene(_ scene: UIScene, continue userActivity: NSUserActivity) {
    guard userActivity.activityType == NSUserActivityTypeBrowsingWeb,
          let url = userActivity.webpageURL else {
        return
    }
    handleUniversalLink(url)
}

3. App Intents Setup

1. Create entities for Spotlight indexing
2. Implement OpenIntent for each content type
3. Define AppShortcuts for Siri phrases
4. Index entities with CSSearchableIndex

Testing

URL Schemes

bashCopy code
# Simulator
xcrun simctl openurl booted "myapp://items/123"

# Device
# Open Safari and navigate to myapp://items/123

Universal Links

bashCopy code
# Test AASA file
curl -I "https://yourapp.com/.well-known/apple-app-site-association"
# Should return Content-Type: application/json

# Validate with Apple
# Use Apple's tool or Branch.io validator

App Intents

1. Build and run on device
2. Open Shortcuts app
3. Your app's shortcuts should appear
4. Test with Siri: "Hey Siri, [your phrase]"

References

• Supporting Universal Links
• App Intents Framework
• Defining Custom URL Schemes
• Making App Entities Available in Spotlight