Skip to main content

Create Dynamic Links on iOS

Create dynamic or unified links programmatically from your Swift code using the ULink SDK.

Prerequisites​

Before creating links, ensure you've completed the SDK setup:

SDK Integration​

  • ULinkSDK installed and initialized in your app
  • ULink.initialize called in your AppDelegate with valid configuration
  • API key generated from Dashboard → Settings → API Keys → Generate API Key
  • Domain configured in your project (Domains → Add Domain)

If you haven't completed these steps, follow the iOS Getting Started guide to set up the SDK and configure your project.

Before creating links, understand the difference between the two types:

Unified vs. Dynamic Links

Unified Links

  • Redirect users based on platform (iOS/Android/Desktop)
  • Do not carry parameters into the app
  • Best for: Marketing campaigns, App Store redirects, simple sharing
  • Example use case: Share a link that opens the App Store on iOS, Play Store on Android, or a website on desktop

Dynamic Links

  • Include structured parameters for deep linking
  • Best for: In-app navigation, personalized content, tracking campaigns
  • Example use case: Share a product link that opens directly to that product screen in your app

Dynamic links include parameters that your app can use for navigation and personalization.

Use the ULinkParameters.dynamic() factory method to create parameters:

let params = ULinkParameters.dynamic(
  domain: "links.shared.ly",  // Your configured domain
  slug: "promo-\(UUID().uuidString.prefix(6))",  // Optional: unique identifier
  fallbackUrl: "https://example.com",  // Web fallback
  iosFallbackUrl: "https://apps.apple.com/app/id123",  // iOS fallback (App Store)
  androidFallbackUrl: "https://play.google.com/store/apps/details?id=com.app",  // Android fallback
  parameters: [
    "screen": "promo",
    "campaign": "spring",
    "productId": "12345"
  ],
  socialMediaTags: SocialMediaTags(
    ogTitle: "Spring Sale - 50% Off!",
    ogDescription: "Don't miss our biggest sale of the year",
    ogImage: "https://example.com/sale-image.jpg"
  )
)
Required Parameters
  • domain: Must be a domain you've configured in your ULink dashboard. This is required for all link types.
  • fallbackUrl: Required for dynamic links - where users land if the app isn't installed
Parameter Best Practices
  • Slug: Make it descriptive and unique. If omitted, ULink generates one automatically.
  • Parameters: Use these for in-app navigation (e.g., screen, productId, userId)
  • Social Media Tags: Improve link previews when shared on social platforms
  • Fallback URLs: Always provide fallbacks so links work even when the app isn't installed

Call createLink with your parameters. This is an async operation:

Task {
  do {
    let response = try await ULink.shared.createLink(parameters: params)
    
    if response.success, let url = response.url {
      print("Link created successfully: \(url)")
      // Share the link or save it for later use
    } else {
      print("Failed to create link: \(response.error ?? "Unknown error")")
    }
  } catch {
    print("Error creating link: \(error.localizedDescription)")
  }
}
Error Handling

Always check response.success before using the link. Common errors include:

  • Invalid domain configuration
  • Slug conflicts: If you use a slug that already exists in your domain, the API will return an error. Each slug must be unique per domain.
  • Missing required parameters
  • Network errors

If you receive a slug conflict error, either:

  • Use a different slug for the new link
  • Use the update API endpoint to modify the existing link with that slug

Response Structure​

The createLink method returns a ULinkResponse with the following structure:

struct ULinkResponse {
    let success: Bool
    let url: String?           // The created link URL
    let error: String?         // Error message if creation failed
    let data: [String: Any]?   // Additional response data
}

Example response data:

{
  "success": true,
  "url": "https://links.shared.ly/promo-123abc",
  "data": {
    "slug": "promo-123abc",
    "shortUrl": "https://links.shared.ly/promo-123abc"
  }
}

Unified links are simpler - they just redirect based on platform without carrying parameters.

let params = ULinkParameters.unified(
  domain: "links.shared.ly",
  slug: "app-download",  // Optional
  iosUrl: "https://apps.apple.com/app/id123",  // Required
  androidUrl: "https://play.google.com/store/apps/details?id=com.app",  // Required
  fallbackUrl: "https://example.com",  // Required
  socialMediaTags: SocialMediaTags(
    ogTitle: "Download Our App",
    ogDescription: "Get the best experience with our mobile app",
    ogImage: "https://example.com/app-preview.jpg"
  )
)
Unified Link Requirements
  • iosUrl: Required - where iOS users should be redirected
  • androidUrl: Required - where Android users should be redirected
  • fallbackUrl: Required - where desktop users or fallback cases go
  • parameters: Not supported in unified links (use dynamic links if you need parameters)
Task {
  do {
    let response = try await ULink.shared.createLink(parameters: params)
    
    if response.success, let url = response.url {
      print("Unified link created: \(url)")
    }
  } catch {
    print("Error: \(error.localizedDescription)")
  }
}

3. Complete Example​

Here's a complete example showing how to create and use a dynamic link:

import ULinkSDK

class LinkCreator {
    func createProductLink(productId: String, productName: String) async throws -> String? {
        let params = ULinkParameters.dynamic(
            domain: "links.shared.ly",
            slug: "product-\(productId)",
            fallbackUrl: "https://myshop.com/products/\(productId)",
            iosFallbackUrl: "https://apps.apple.com/app/myshop",
            androidFallbackUrl: "https://play.google.com/store/apps/details?id=com.myshop",
            parameters: [
                "screen": "product",
                "productId": productId,
                "productName": productName
            ],
            socialMediaTags: SocialMediaTags(
                ogTitle: productName,
                ogDescription: "Check out \(productName) in our app",
                ogImage: "https://myshop.com/images/\(productId).jpg"
            )
        )
        
        let response = try await ULink.shared.createLink(parameters: params)
        
        guard response.success, let url = response.url else {
            throw NSError(domain: "LinkCreation", code: -1, 
                         userInfo: [NSLocalizedDescriptionKey: response.error ?? "Unknown error"])
        }
        
        return url
    }
}

// Usage
Task {
    do {
        let linkCreator = LinkCreator()
        if let link = try await linkCreator.createProductLink(
            productId: "12345",
            productName: "Amazing Product"
        ) {
            // Share the link
            print("Share this link: \(link)")
        }
    } catch {
        print("Failed to create link: \(error)")
    }
}

Best Practices​

  • Slugs must be unique: Each slug can only be used once per domain. If you try to create a link with an existing slug, it will return an error. Use unique slugs for each link.
  • Validate before sharing: Always check response.success before sharing or storing the link
  • Handle errors gracefully: Provide user feedback if link creation fails, especially for slug conflicts
  • Use descriptive slugs: Make slugs meaningful (e.g., product-12345 instead of random strings) but ensure they're unique

Social Media Tags​

  • Always include OG tags: Better link previews improve click-through rates
  • Use high-quality images: OG images should be at least 1200x630 pixels
  • Write compelling descriptions: Keep descriptions under 200 characters for best display

Parameters​

  • Keep parameters simple: Use flat key-value pairs for best compatibility
  • Avoid sensitive data: Don't put passwords, tokens, or PII in parameters
  • Use consistent keys: Establish a naming convention (e.g., screen, productId, userId)

Next Steps​

Once you've created links, learn how to handle them when users tap them: