Skip to main content

iOS Getting Started

Everything you need to install the iOS SDK, wire it to your project, and validate the flow.

What are the prerequisites?​

Development Environment​

  • Xcode 15+ and iOS 13+ deployment target
  • URL scheme for your app (e.g. myapp)
  • ULink account and project (create one here)
  • API key generated from Dashboard → Settings → API Keys → Generate API Key
  • Domain configured in your project (Domains → Add Domain)

How to install the SDK?​

Swift Package Manager​

  1. File → Add Packages…
  2. URL: https://github.com/mohn93/ios_ulink_sdk.git
  3. Select the latest release (e.g. 1.0.2) and add the ULinkSDK product to your target.

CocoaPods​

Podfile
platform :ios, '13.0'
use_frameworks!

target 'YourApp' do
  pod 'ULinkSDK', '1.0.2'
end

Run pod install.

Before initializing the SDK, you need to configure your app to handle incoming links. iOS supports two types of deep links:

  • URL Schemes (e.g., myapp://) - Custom URL schemes that always open your app
  • Universal Links (e.g., https://yourdomain.com) - HTTPS links that open your app when installed, or fall back to Safari

Step 1: Configure URL Scheme​

URL schemes allow your app to be opened via custom URLs like myapp://path/to/content.

  1. Open your project in Xcode
  2. Select your app target in the project navigator
  3. Go to the Info tab
  4. Scroll down to URL Types section
  5. Click the + button to add a new URL Type
  6. Fill in the following:
    • Identifier: com.yourapp.deeplink (use your app's bundle identifier)
    • URL Schemes: Enter your scheme (e.g., myapp - this will create URLs like myapp://)
    • Role: Editor
URL Scheme Best Practices
  • Use lowercase letters and numbers only
  • Keep it short and memorable (e.g., myapp, shop, news)
  • Avoid special characters or spaces

Universal links work better for sharing because they work even when the app isn't installed. They require setting up Associated Domains.

  1. In Xcode, select your app target
  2. Go to the Signing & Capabilities tab
  3. Click + Capability and select Associated Domains
  4. Click + under Domains to add a new domain
  5. Enter your domain in the format: applinks:yourdomain.com or applinks:links.shared.ly
    • Replace yourdomain.com with the domain you configured in the ULink dashboard
    • The applinks: prefix is required by iOS
    • For shared domains, use: applinks:links.shared.ly (or your custom subdomain)
Domain Configuration

The domain you add here must match exactly with the domain configured in your ULink dashboard under Domains. If you're using a shared domain like links.shared.ly, make sure it's added in both places.

Step 3: Add URL Handling to AppDelegate​

Your app needs to forward incoming URLs to the ULink SDK. Add these methods to your AppDelegate:

import ULinkSDK

@main
class AppDelegate: UIResponder, UIApplicationDelegate {
  
  func application(
    _ application: UIApplication,
    didFinishLaunchingWithOptions launchOptions: [UIApplication.LaunchOptionsKey: Any]? = nil
  ) -> Bool {
    // Initialize ULink SDK
    Task {
      let _ = await ULink.initialize(
        config: ULinkConfig(
          apiKey: "ULINK_API_KEY",
          baseUrl: "https://api.ulink.ly",
          debug: true
        )
      )
    }
    return true
  }
  
  // Handle custom URL schemes (e.g., myapp://)
  func application(
    _ app: UIApplication,
    open url: URL,
    options: [UIApplication.OpenURLOptionsKey : Any] = [:]
  ) -> Bool {
    return ULink.shared.handleIncomingURL(url)
  }
  
  // Handle universal links (e.g., https://yourdomain.com)
  func application(
    _ application: UIApplication,
    continue userActivity: NSUserActivity,
    restorationHandler: @escaping ([UIUserActivityRestoring]?) -> Void
  ) -> Bool {
    guard userActivity.activityType == NSUserActivityTypeBrowsingWeb,
          let url = userActivity.webpageURL else {
      return false
    }
    return ULink.shared.handleIncomingURL(url)
  }
}
SwiftUI Apps

If you're using SwiftUI with @main and App, you can handle URLs using the .onOpenURL modifier instead. See the Receive Links guide for SwiftUI examples.

How to configure Dashboard Settings?​

Now that your app is configured, you need to match those settings in the ULink dashboard.

  1. Open your ULink project in the dashboard
  2. Navigate to Configuration → General
  3. Enter your app's Bundle ID (found in Xcode under your target's General tab)
  4. Enter your URL Scheme (the scheme you configured in step 3.1, e.g., myapp - without the ://)
  5. Navigate to Domains section
  6. If you haven't already, add your domain:
    • For shared domains: Click Add Domain → Select Shared Domain (.shared.ly) → Enter your subdomain
    • For custom domains: Click Add Domain → Enter your custom domain → Complete DNS verification
  7. Ensure the domain matches exactly what you entered in Associated Domains (step 3.2)
Matching Configuration
  • The Bundle ID in the dashboard must match your Xcode project's bundle identifier
  • The URL Scheme in the dashboard must match the scheme you added in URL Types
  • The Domain in the dashboard must match the domain in your Associated Domains (without the applinks: prefix)

Frequently Asked Questions (FAQ)​

How do I verify the integration?​

  1. Navigate to Links → Create Link.
  2. Choose Unified for App Store/website routing or Dynamic for deep link parameters.
  3. Set a short Slug, iOS URL, and Fallback URL.
  4. Save the link and copy the short URL.
  5. Install a build containing the ULink SDK on your device.
  6. Tap the short URL from Notes or email.
    • If installed, the app should launch and receive data.
    • If missing, it should redirect to the fallback URL.

Where can I see analytics?​

In Links, confirm the click counter increments. Click the Analytics button for that specific link to open its analytics page and ensure the platform is iOS.

If metrics don’t update or the app doesn't open, review Troubleshoot & Test Deep Links for debugging tips.