iOS SDK

The Uplink iOS SDK embeds a worker inside your iOS app, making the device controllable from server-side code written with the JavaScript SDK. Use it when you want Uplink automation to run inside your own branded app.

Key concepts:

Device: A physical iOS device running your app
Worker: A worker created by the Uplink SDK inside your app (one app can create multiple workers)
Session: An authenticated connection that pairs your worker with a JavaScript SDK client

Requirements

iOS 15.0 or later
Xcode 26 or later

Installation

The iOS SDK is distributed via Swift Package Manager.

Add the package

In Xcode, go to File → Add Package Dependencies… and enter:

https://github.com/uplink-code/uplink-ios-public

Select the Uplink product

Choose the Uplink library product and add it to your app target. It bundles its MuppetIOS browser engine dependency, so you only link one product.Choose Uplink-Dynamic instead only when your integration requires dynamic frameworks.

Import the module

import Uplink

If you manage dependencies with a Package.swift file:

dependencies: [
    .package(url: "https://github.com/uplink-code/uplink-ios-public", from: "1.0.0")
],
targets: [
    .target(
        name: "YourApp",
        dependencies: [
            .product(name: "Uplink", package: "uplink-ios-public")
        ]
    )
]

Quick example

import UIKit
import Uplink

@MainActor
func startUplink(in viewController: UIViewController, session sessionUrl: String) async throws {
    let worker = await Worker(controller: viewController)

    try await worker.connect(session: sessionUrl)

    Task {
        await worker.accept()
    }
}

Creating a worker

`Worker(controller:)`

Worker is an actor. Its initializer is async and binds the worker to a UIViewController. The SDK uses the controller to host its WKWebView, so pass the view controller that should own the SDK’s browser surface (typically the one currently on screen).

init(controller: UIViewController) async

Parameters:

controller: The UIViewController that will host the SDK’s web view

let worker = await Worker(controller: self)

Create one worker per session. There is no shared Uplink object to configure first.

Keep a strong reference to the Worker for as long as the connection is active. If the worker is deallocated, the session will close.

Obtaining a session

Your backend creates a session using the JavaScript SDK’s uplink.session() and delivers the resulting session URL to the app. How you deliver it — a backend API response, a universal link, a QR code — is up to you.

let sessionUrl: String = // from your backend, deep link, or QR code

See Sessions for how sessions are created on the server side.

Connecting and accepting

`worker.connect(session:)`

Connects the worker to an Uplink session.

func connect(session: String) async throws(UplinkError)

Parameters:

session: The session URL provided by your backend

Throws: UplinkError.unableToConnectToUplink if the session can’t be joined.

try await worker.connect(session: sessionUrl)

`worker.accept()`

Begins accepting commands from the JavaScript SDK client. accept() does not throw, and it suspends until the worker closes, so call it from a Task if you want the rest of your app to continue running.

func accept() async

Task {
    await worker.accept()
}

Watching events

`worker.watch(_:)`

Registers a callback for events the worker emits. Call it before connect so you don’t miss the connection events.

func watch(_ callback: @escaping @Sendable (any Event) async -> Void)

Events are enums that conform to Event. Match on the ones you care about:

Type	Cases
`WorkerEvent`	`.connected(Address)`, `.terminated(Address)`, `.closed(Address)`
`BrowserEvent`	`.created(handle:)`, `.closed(handle:)`
`PageEvent`	`.created(handle:)`, `.request(url:method:headers:)`, `.response(url:status:headers:)`, `.closed(handle:)`

await worker.watch { event in
    switch event {
    case WorkerEvent.terminated:
        print("worker terminated")
    case PageEvent.request(let url, _, _):
        print("page requested \(url)")
    default:
        break
    }
}

Cleanup

`worker.close()`

Closes the worker and releases its resources. Returns once the session has finished closing.

func close() async

await worker.close()

Closing a worker ends its session. Any browsers the JavaScript SDK has launched on the worker will be terminated.

Debug logging

UplinkDebug.setDebug(isEnabled:forwardLogs:) turns on verbose SDK logging and optionally forwards each line to your own logger.

await UplinkDebug.setDebug(isEnabled: true) { line in
    myLogger.debug(line)
}

Complete example

A minimal UIViewController that starts an Uplink worker when it appears:

import UIKit
import Uplink

final class UplinkViewController: UIViewController {
    private var worker: Worker?

    func start(sessionUrl: String) {
        Task { @MainActor in
            let worker = await Worker(controller: self)
            self.worker = worker

            do {
                try await worker.connect(session: sessionUrl)
                await worker.accept()
            } catch {
                print("Uplink worker failed to connect: \(error)")
            }
        }
    }

    override func viewWillDisappear(_ animated: Bool) {
        super.viewWillDisappear(animated)

        Task { [worker] in
            await worker?.close()
        }
    }
}

Android SDK

Integrate Uplink into your Android app

JavaScript SDK

Control your worker from server-side code

Sessions

How sessions are created and secured

Core concepts

Architecture overview

JavaScript SDK

Native SDK

Page API

AI Automation

Requirements

Installation

Quick example

Creating a worker

`Worker(controller:)`

Obtaining a session

Connecting and accepting

`worker.connect(session:)`

`worker.accept()`

Watching events

`worker.watch(_:)`

Cleanup

`worker.close()`

Debug logging

Complete example

Android SDK

JavaScript SDK

Sessions

Core concepts

​Requirements

​Installation

​Quick example

​Creating a worker

​Worker(controller:)

​Obtaining a session

​Connecting and accepting

​worker.connect(session:)

​worker.accept()

​Watching events

​worker.watch(_:)

​Cleanup

​worker.close()

​Debug logging

​Complete example

​Related

Android SDK

JavaScript SDK

Sessions

Core concepts

Requirements

Installation

Quick example

Creating a worker

`Worker(controller:)`

Obtaining a session

Connecting and accepting

`worker.connect(session:)`

`worker.accept()`

Watching events

`worker.watch(_:)`

Cleanup

`worker.close()`

Debug logging

Complete example

Related