Skip to main content

📱 Handle Universal Links in iOS

Universal Links let your iOS app open directly when a user taps a ChottuLink. This ensures a seamless experience without falling back to a browser if the app is installed.

🛠 Prerequisites​

Before generating links, ensure:

  • Set up your project
  • Configure iOS app settings
  • Get your API key
  • Using Swift Package Manager (recommended)
  • Or manual installation
  • Add initialization code to AppDelegate
  • Configure Universal Links

🔧 Implementation Guide​

To respond to dynamic links, your app should conform to the ChottuLinkDelegate protocol. This allows you to receive, parse, and act upon ChottuLink events when a link is opened.

tip

🔁 You’ll need to pass your delegate to the ChottuLink SDK during initialization.

// Initialize ChottuLink SDK with delegate
// Replace "your-api-key" with your actual Mobile SDK key e.g. chottulink_xxxxxxxxxxxxxxxxxxxxxxxx

let config = CLConfiguration(apiKey: "your-api-key", delegate: self)
ChottuLink.initialize(config: config)

Implement the Delegate​

Ensure your class (e.g., AppDelegate or a dedicated handler) implements the required delegate method:

import ChottuLinkSDK

class AppDelegate: ChottuLinkDelegate {
    
    // Called when a deep link or deferred link is successfully resolved
    func chottuLink(didResolveDeepLink link: URL, metadata: [String : Any]?) {
        
        print("✅ link received: \(link.absoluteString)")
        
        // Tip: ➡️ Navigate to a specific page or take action based on the link

        if let metadata = metadata {
        
            print("📦 Metadata: \(metadata)")
            
            // Metadata contains the following keys (available since v1.0.7+):
            // - isDeferred: Bool         Indicates if the link is deferred
            // - originalURL: String      The resolved destination URL (may be nil if not found)
            // - resolvedAt: Date         Timestamp when the link was resolved
            // - shortLinkRaw: String     The deeplink url which was clicked with all the parameters intact
        }
    }
    
    // Called when there's an error resolving the deep link
   func chottuLink(didFailToResolveDeepLink originalURL: URL?, error: any Error) {
   
        print("❌ Failed to resolve deep link: \(error.localizedDescription)")
    }
}
Method 1: Using SwiftUI
import ChottuLinkSDK
import SwiftUI

struct ContentView: View {
        
    var body: some View {
        
        VStack {
            // Your app content
        }
        .padding()
        .onOpenURL { url in
            // Handle the incoming URL
            ChottuLink.handleLink(url) 
        }
    }
}
Method 2: Using SceneDelegate

Add the below code in your SceneDelegate.swift file:

import ChottuLinkSDK
import UIKit

class SceneDelegate: UIResponder, UIWindowSceneDelegate {

  var window: UIWindow?
  
  // Handles Universal Links when the app is launched from a terminated state
  func scene(_ scene: UIScene, willConnectTo session: UISceneSession, options connectionOptions: UIScene.ConnectionOptions) {
  
    guard let userActivity = connectionOptions.userActivities.first,
          let url = userActivity.webpageURL else {
          
          return
    }
    
    // Handle the incoming URL from app launch
    ChottuLink.handleLink(url)
  }

  // Handles Universal Links when the app is already running in the foreground or background
  func scene(_ scene: UIScene, continue userActivity: NSUserActivity) {
  
      guard userActivity.activityType == NSUserActivityTypeBrowsingWeb,
            let url = userActivity.webpageURL else {
            
          return
      }
      
      // Handle the incoming URL from app resume
      ChottuLink.handleLink(url)
  }
}

3. Test the Integration​

You can test your Universal Link setup by:

  • Installing your app on a physical device (not a simulator).
  • Tapping on the Dynamic Link.
  • Verifying that your app opens and the link is processed.

🛠 Troubleshooting​

  • Ensure the domain is listed under Associated Domains in your project on Xcode
  • Ensure you have enabled Universal Links checkbox in the iOS section on ChottuLink settings

URL Processing

Advancedv1.0.3+

Process the shortened Deeplink using the getAppLinkDataFromUrl method.
This retrieves the associated app link data and returns a ResolvedLink object containing the resolved destination URL and the original short link.

💡 Method Signature

New Feature

This method was introduced in SDK version v1.0.3+

func getAppLinkDataFromUrl(from shortURL: String) async throws -> ResolvedLink
📥 Parameters
ParameterTypeRequiredDescription
shortURLString✅ YesThe shortened URL string to be resolved
📤 Return Value

A ResolvedLink object containing:

  struct ResolvedLink: Codable, Sendable {
      let isDeferred: Bool   // Indicates if the link is deferred
      let link: URL?         // The resolved destination URL (may be nil if not found)
      let shortLink: URL?    // The original short or branded link that was provided
      let shortLinkRaw: URL? // The deeplink url which was clicked with all the parameters intact
  }
⚠️ Error Handling

Note: This method can throw various errors. Always implement proper error handling.

  • ChottuLinkError.notInitialized – If SDK is not initialized
  • ChottuLinkError.invalidURL – If the URL is malformed
  • ChottuLinkError.invalidAPIKey – If the API key is not available
  • ChottuLinkError.invalidResponse – If the server response is invalid
  • Network errors if the request fails

💻 Basic Implementation

Task {
    do {
        let link = "https://yourapp.chottu.link/summer-sale"
        let appLinkData = try await ChottuLink.getAppLinkDataFromUrl(from: link)
        
        if let destinationURL = appLinkData.link {
            print("✅ Resolved URL: \(destinationURL.absoluteString)")
            // Navigate to the destination
        }
    } catch {
        print("❌ Failed to get app link data: \(error)")
    }
}

🎯 Use Cases

  • Manual Link Processing: Process links from user input
  • Testing: Test deep link functionality
  • Background Processing: Process links in background tasks
  • Link Validation: Validate links before processing