InstaSDK

InstaSDK is the entry point of the SDK. It holds the credentials and routing information every other component reads: the partner identity sent with each request, the server region, and the deployment environment.

Nothing else in the SDK works until configure has been called. Calls made before configuration fail with IVError.sdkNotConfigured.

public final class InstaSDK

---

Accessing the instance

public static let shared: InstaSDK

The only instance. InstaSDK cannot be constructed directly.

---

Configuration

configure(_:partnerId:region:environment:)

public func configure(
    _ clientId: String = SDKConfig.clientId,
    partnerId: String,
    region: ServerRegion = .us,
    environment: Environment = .production
)

Configures the SDK. Call this once, as early as possible — in application(_:didFinishLaunchingWithOptions:) for UIKit, or the App initialiser for SwiftUI.

Parameter	Default	Description
clientId	SDKConfig.clientId	Client identifier. Leave at the default unless InstaVision issued you a specific one.
partnerId	—	Your partner identifier, issued by InstaVision. Required.
region	.us	Data residency region. Leave at the default unless InstaVision has told you otherwise.
environment	.production	Deployment target. Use .staging or .dev only with non-production credentials.

Beyond storing these values, configure starts the real-time message channel if a user token is already present — so if the user was signed in when the app last exited, onSSEMessage begins delivering messages immediately after configuration.

InstaSDK.shared.configure(
    partnerId: "your-partner-id",
    region: .us,
    environment: .production
)

See Getting Started for installation and the rest of the app setup.

setRegion(_:)

public func setRegion(_ region: ServerRegion)

Changes the server region after configuration. Because the region determines which backend the SDK talks to, change it only while signed out — an access token issued in one region is not valid in another. Most integrations never call this and stay on the .us default.

setPartnerId(_:)

public func setPartnerId(_ partnerId: String)

Replaces the partner identifier after configuration.

setAuthToken(_:)

public func setAuthToken(_ token: String)

Stores a user access token, as if the user had just signed in, and it is picked up by every subsequent service call. Use this when your app obtains a token outside the SDK’s own sign-in flows. Equivalent to Factory.userService.saveToken(_:).

---

Callbacks

refreshAuthToken

public var refreshAuthToken: (() -> String)?

Called when a request is rejected because the access token has expired. Return a fresh token and the request is retried with it. If the closure is nil or returns an expired token, the request fails with IVError.refreshTokenExpired and the sessionTokenExpired notification is posted.

If you sign in through the SDK’s own flows you do not normally need to set this. Use it when your app manages tokens itself.

onSSEMessage

public var onSSEMessage: ((SSEMessage?) -> Void)?

Receives real-time messages pushed from the backend, such as lullaby playback state changes.

Set it before or immediately after configure, since messages start flowing as soon as an authenticated channel is established. There is only one closure, so assigning it twice replaces the first handler — in an app with several interested screens, fan out from a single handler rather than reassigning it per screen.

InstaSDK.shared.onSSEMessage = { message in
    guard let message else { return }
    switch message.payload {
    case let .lullabyStateUpdated(state):
        // Playback state changed on a baby monitor camera.
        break
    case let .any(payload):
        // An unrecognised message type, delivered as a dictionary.
        break
    }
}

The closure is not guaranteed to be called on the main queue — hop to main before touching UI.

The channel is best-effort: a message can be missed while the app is suspended or the network is down. Use messages to keep the UI live, but still refetch when a screen appears and when the app returns to the foreground.

---

Environments and regions

public enum Environment {
    case production
    case staging
    case dev
}

public enum ServerRegion: String {
    case us = "US"
}

The environment case is .production, not .prod. region selects data residency and is only meaningful in .production; staging and dev each have a single backend. Leave region at its .us default unless InstaVision has told you otherwise.

Point a debug build at staging with a compile-time flag rather than shipping a runtime switch:

#if DEBUG
let environment: Environment = .staging
#else
let environment: Environment = .production
#endif

---

Session expiry

public extension Notification.Name {
    static let sessionTokenExpired: Notification.Name
}

Posted when the SDK cannot refresh an expired session. Observe it once, at the top of your app, so a session that expires between requests is handled in one place rather than in every call site.

NotificationCenter.default.addObserver(
    forName: .sessionTokenExpired,
    object: nil,
    queue: .main
) { _ in
    Factory.userService.localLogout()
    LiveViewObjectStore.logout()
    // present your sign-in screen
}

---

Complete setup

import SwiftUI
import IVSDK

@main
struct YourApp: App {
    init() {
        InstaSDK.shared.configure(
            partnerId: "your-partner-id",
            region: .us,
            environment: .production
        )

        InstaSDK.shared.onSSEMessage = { message in
            // Real-time updates from the backend.
        }
    }

    var body: some Scene {
        WindowGroup { ContentView() }
    }
}