iOS SDK

The iOS SDK (TolinkuSDK) provides Universal Link handling, deferred deep linking, event tracking, referrals, and in-app messages for iOS 15+ and macOS 13+.

Installation

Add the SDK via Swift Package Manager in Xcode:

1. Go to File > Add Package Dependencies.
2. Enter the repository URL: https://github.com/tolinku/ios-sdk
3. Select the latest version and add the TolinkuSDK library to your target.

Setup

Configure the SDK as early as possible in your app lifecycle:

import TolinkuSDK

// In your App init or AppDelegate:
do {
    let tolinku = try Tolinku.configure(apiKey: "tolk_pub_your_key")
} catch {
    print("Tolinku configuration failed: \(error)")
}

Optionally specify a custom base URL:

try Tolinku.configure(
    apiKey: "tolk_pub_your_key",
    baseURL: "https://your-app.tolinku.com"
)

Access the shared instance anywhere in your app:

// Optional access (nil before configure)
Tolinku.shared?.track("custom.screen_view")

// Throwing access (throws TolinkuError.notConfigured)
let tolinku = try Tolinku.requireShared()

User identification

Tolinku.shared?.setUserId("user_123")

// Clear on logout
Tolinku.shared?.setUserId(nil)

Event tracking

// Simple event
await Tolinku.shared?.track("custom.app_open")

// Event with properties
await Tolinku.shared?.track("custom.purchase", properties: [
    "amount": .string("29.99"),
    "currency": .string("USD")
])

// Force flush
await Tolinku.shared?.flush()

Events are batched (10 events or 5-second timer) and auto-flushed when the app enters the background.

Ecommerce tracking

Track purchases, cart activity, and product events via ecommerce:

let tolinku = try Tolinku.requireShared()
tolinku.setUserId("user_123")

// Track a purchase
await tolinku.ecommerce.purchase(
    transactionId: "order_456",
    revenue: 49.99,
    currency: "USD",
    items: [TolinkuItem(itemId: "sku_1", itemName: "T-Shirt", price: 24.99, quantity: 2)]
)

// Track product views and cart events
await tolinku.ecommerce.viewItem(
    items: [TolinkuItem(itemId: "sku_1", itemName: "T-Shirt", price: 24.99)]
)
await tolinku.ecommerce.addToCart(
    items: [TolinkuItem(itemId: "sku_1", quantity: 1)]
)
await tolinku.ecommerce.beginCheckout()

// Search and ratings
await tolinku.ecommerce.search(searchTerm: "shoes")
await tolinku.ecommerce.rate(itemId: "sku_1", rating: 4.5, maxRating: 5)

// Force flush
await tolinku.ecommerce.flush()

Ecommerce events are batched (10 events or 5-second timer) and auto-flushed when the app enters the background. The SDK manages cart IDs automatically via UserDefaults, clearing them after purchase. All money values use Swift Decimal for precision.

Note

Ecommerce tracking requires a paid plan (Standard or above).

Handling Universal Links

Parse incoming Universal Links using the static helper:

// UIKit AppDelegate
func application(
    _ application: UIApplication,
    continue userActivity: NSUserActivity,
    restorationHandler: @escaping ([UIUserActivityRestoring]?) -> Void
) -> Bool {
    guard userActivity.activityType == NSUserActivityTypeBrowsingWeb,
          let url = userActivity.webpageURL,
          let result = Tolinku.handleUniversalLink(url) else {
        return false
    }

    // result.path - e.g. "/merchant/abc123"
    // result.queryItems - any query parameters
    navigateToDeepLink(path: result.path)
    return true
}

For SwiftUI:

@main
struct MyApp: App {
    init() {
        try? Tolinku.configure(apiKey: "tolk_pub_your_key")
    }

    var body: some Scene {
        WindowGroup {
            ContentView()
                .onOpenURL { url in
                    if let result = Tolinku.handleUniversalLink(url) {
                        // Navigate to result.path
                    }
                }
        }
    }
}

Tip

You also need to configure Associated Domains and your AASA file. See Universal Links (iOS) for the full setup guide.

Deferred deep linking

Claim the original link destination after the user installs your app:

// Signal-based claiming (recommended for iOS)
if let link = try await Tolinku.shared?.deferred.claimBySignals(
    appspaceId: "your_appspace_id"
) {
    // Navigate to link.deep_link_path
}

The SDK automatically collects timezone, language, and screen dimensions for fingerprint matching.

Token-based claiming is also available (for cases where you have a referrer token):

if let link = try await Tolinku.shared?.deferred.claimByToken("token") {
    // Navigate to link.deep_link_path
}

Referrals

let referrals = Tolinku.shared!.referrals

// Create a referral code
let result = try await referrals.create(userId: "user_123", userName: "Jane")
print(result.referral_code) // "ABC123"
print(result.referral_url)  // "https://myapp.tolinku.com/ref/ABC123"

// Look up a referral
let info = try await referrals.get(code: "ABC123")

// Link a referred user (status stays pending until reward milestone is reached)
try await referrals.complete(code: "ABC123", referredUserId: "user_456")

// Update milestone (completes the referral if it matches the reward milestone)
try await referrals.milestone(code: "ABC123", milestone: "first_purchase")

// Claim reward (after granting it in your system)
try await referrals.claimReward(code: "ABC123")

// Get leaderboard
let leaders = try await referrals.leaderboard(limit: 10)

Tip

If you have ecommerce auto-completion enabled, you don’t need to call milestone() manually. Just track the purchase via Tolinku.shared?.ecommerce.purchase() and the server will auto-complete the referral.

In-app messages

Fetch and display messages:

// UIKit: show highest-priority message
await Tolinku.shared?.messages.show(
    trigger: "on_open",
    from: viewController,
    onAction: { action in
        // Handle CTA action URL
    },
    onDismiss: {
        // Message dismissed
    }
)

Messages are rendered in a WKWebView dialog.

Shutdown

Clean up when the app terminates or you need to reconfigure:

await Tolinku.shutdown()