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.6) and add the ULinkSDK product to your target.

CocoaPods​

Podfile
platform :ios, '13.0'
use_frameworks!

target 'YourApp' do
  pod 'ULinkSDK', '~> 1.0.6'
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 {
      do {
        let _ = try await ULink.initialize(
          config: ULinkConfig(
            apiKey: "ULINK_API_KEY",
            baseUrl: "https://api.ulink.ly",
            debug: true
          )
        )
      } catch {
        print("Failed to initialize ULink: \(error)")
      }
    }
    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. These settings are required for ULink to generate the Apple App Site Association (AASA) file that enables Universal Links.

Bundle Identifier​

Your Bundle Identifier uniquely identifies your app to Apple and must match exactly between Xcode and the ULink dashboard.

  1. In Xcode, select your project in the navigator
  2. Select your app target
  3. Go to the General tab
  4. Find the Bundle Identifier field (e.g., com.yourcompany.yourapp)
  5. In the ULink dashboard, go to Configuration → General → iOS
  6. Enter your Bundle Identifier in the Bundle ID field

Team ID​

Your Apple Developer Team ID is required for Universal Links to work. ULink uses it to generate the AASA file in the format TEAM_ID.bundle_id.

Find your Team ID:

  1. Go to Apple Developer Portal
  2. Sign in with your Apple Developer account
  3. Navigate to Membership in the left sidebar
  4. Copy your Team ID (a 10-character alphanumeric string like ABC123DEF4)

Add to ULink dashboard:

  1. In the ULink dashboard, go to Configuration → General → iOS
  2. Enter your Team ID in the Team ID field
Finding Team ID in Xcode

You can also find your Team ID in Xcode:

  1. Open your project in Xcode
  2. Select your project in the navigator
  3. Select your target → Signing & Capabilities tab
  4. Look at your Team dropdown — the Team ID appears in parentheses next to the team name
  5. Alternatively, check your provisioning profile details in the Signing section

URL Scheme​

Enter the URL scheme you configured earlier (Step 1) without the :// suffix.

  1. In the ULink dashboard, go to Configuration → General → iOS
  2. Enter your URL Scheme (e.g., myapp — not myapp://)

Domain Configuration​

  1. Navigate to the Domains section in your project
  2. 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
  3. Ensure the domain matches exactly what you entered in Associated Domains (without the applinks: prefix)
Matching Configuration
  • The Bundle ID in the dashboard must match your Xcode project's bundle identifier
  • The Team ID in the dashboard must match your Apple Developer Team ID
  • 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)

If any of these don't match, Universal Links won't work and links will open in Safari instead of your app.

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.

How can I verify my configuration with the CLI?​

The ULink CLI provides comprehensive verification of your Universal Links setup.

Install the CLI​

# macOS / Linux
curl -fsSL https://ulink.ly/install.sh | bash

# Windows (PowerShell)
irm https://ulink.ly/install.ps1 | iex

Run Verification​

# Authenticate
ulink login

# Link your project
cd /path/to/your/ios-app
ulink project set

# Run verification
ulink verify -v

What the CLI Verifies​

CheckDescription
Info.plistValidates URL schemes (CFBundleURLTypes)
Bundle IDConfirms bundle identifier is configured
EntitlementsChecks for entitlements file existence
Associated DomainsValidates applinks entries in entitlements
AASA fileFetches and validates /.well-known/apple-app-site-association
Team ID matchingVerifies Team ID matches dashboard configuration

Fixing Issues​

The verification report shows exactly what's misconfigured. Common issues:

  • Missing associated domains in entitlements
  • Bundle ID mismatch between Xcode and dashboard
  • Team ID not configured in dashboard
  • AASA file not accessible on domain
tip

Run ulink verify after any Xcode signing or capability changes to catch issues early.