Initialization and configuration¶

Revue.shared is the entry point of the SDK. Before you can add friends, invite them or publish tracks, start the SDK with initialize(_:). When you are done, shut it down with destroy(). Call both on the main thread.

Initialize¶

initialize(_:) takes a Revue.Configuration. Two fields are required:

licenseData: the bytes of your license file. Without it, initialize(_:) throws RevueInitError.
bootstrapNodes: the nodes the SDK uses to join the network. The SDK has no built-in list; see Connection for nodes you can use.

initialize(_:) throws a RevueInitError when the license is missing, malformed, invalid or expired, or when the configuration is invalid. Once it returns, Room.localParticipant on Room.shared is ready.

Right after initialize(_:) returns, add your delegates to Revue.delegates and Room.delegates, on Revue.shared and Room.shared:

Swift

import RevueSDK
import Foundation

/// Start the SDK, then register your delegates. `destroy()` removes every delegate,
/// so register them again after every `initialize(_:)`.
@MainActor
func startRevue(licenseData: Data, bootstrapNodes: [Revue.BootstrapNode],
                delegate: RevueDelegate & RoomDelegate) throws {
    let config = Revue.Configuration(bootstrapNodes: bootstrapNodes, licenseData: licenseData)
    try Revue.shared.initialize(config)

    Revue.shared.delegates.add(delegate: delegate)
    Room.shared.delegates.add(delegate: delegate)
}

Configuration¶

Field	Default	Meaning
`licenseData`	`nil`	License file bytes. Required.
`bootstrapNodes`	none	Nodes used to join the network. Required.
`savedataFileName`	`nil` (`revue.bin`)	File name of the identity save file, without a path. It must not contain `/` or `..`.
`savedataPassword`	`nil`	Password that encrypts the save file.
`networkOptions`	`Revue.NetworkOptions.default`	Transport switches and port range. Read only at initialize.
`mqttOptions`	`nil`	Presence service settings. `nil` uses the built-in service. `.deferred` starts presence later; see Start presence after sign-in.

Every field is read once, by initialize(_:). To change one, destroy the SDK and initialize it again.

An App that has no MQTT account at launch can initialize first and start presence later. Set mqttOptions to Revue.MqttOptions.deferred: initialize(_:) then does not contact the broker and sends no presence events. Calls and friend connections work as usual. Call startPresence(_:) once you have the account:

Swift

import RevueSDK
import Foundation

/// Start the SDK without presence, because there is no MQTT account yet.
@MainActor
func startRevueWithoutPresence(licenseData: Data, bootstrapNodes: [Revue.BootstrapNode],
                               delegate: RevueDelegate & RoomDelegate) throws {
    let config = Revue.Configuration(bootstrapNodes: bootstrapNodes, licenseData: licenseData,
                                     mqttOptions: .deferred)
    try Revue.shared.initialize(config)

    Revue.shared.delegates.add(delegate: delegate)
    Room.shared.delegates.add(delegate: delegate)
}

/// After sign-in, start presence with the account. Call it again to switch accounts.
@MainActor
func startPresenceAfterSignIn(username: String, password: String) async throws {
    let options = Revue.MqttOptions(brokerUrl: "wss://broker.example.com/mqtt",
                                    username: username, password: password)
    try await Revue.shared.startPresence(options)
}

/// After sign-out, stop presence. Calls and friend connections keep working.
@MainActor
func stopPresenceAfterSignOut() async {
    await Revue.shared.stopPresence()
}

When startPresence(_:) returns without an error, the request has been sent. It does not mean presence is connected: wait for .connected in revue(_:didUpdatePresenceConnectionState:).
To switch accounts, call startPresence(_:) again with the new settings. The old connection closes first, so you get .notInitialized, then .connected. Calls run in the order you made them.
To sign out, call stopPresence(). You get .notInitialized once, and calls and friend connections are not affected.
deferred applies to one initialize(_:). After destroy(), presence stays off until you call startPresence(_:) again.
Passing nil uses the built-in service. deferStart is ignored here.

Known issue

After stopPresence(), friends can see this user go .offline and then return to .online, and stay there, while a friend connection between them is still up. Until this is fixed, call destroy() if friends must see the user as offline.

startPresence(_:) throws a RevuePresenceError:

Error	Meaning
`.notInitialized`	The SDK is not initialized, or `destroy()` is running.
`.invalidConfiguration`	`presenceQos` is outside 0–2, or the core rejected the settings. The running connection is not affected.
`.startFailed(code:)`	The connection request failed and presence is stopped.

Destroy¶

destroy() hangs up every call, stops the SDK and releases its network instance. It is async: wait for it to return before you initialize again.

By default destroy() keeps everything on disk. Pass a Revue.DestroyOptions to delete data after the SDK has stopped:

deleteSavedata: the identity save file of this session and the files that belong to it.
deleteRecordings: every recording.
Revue.DestroyOptions.deleteAllData sets both.

Swift

import RevueSDK

/// Shut the SDK down and delete the identity save file and every recording.
@MainActor
func signOutAndDeleteData() async {
    await Revue.shared.destroy(.deleteAllData)
}

Initialize again¶

Three rules apply every time you restart the SDK, for example after the user changes network settings:

destroy() removes every delegate from Revue.delegates and Room.delegates. Register your delegates again after every initialize(_:).
You cannot call initialize(_:) while the SDK is running; call destroy() first. Calling it too early throws RevueInitError, and the running instance is left as it is.
localParticipant is nil before initialize(_:) and after destroy(). Do not read it outside that window.

Swift

import RevueSDK

/// Apply a new configuration: destroy the running SDK, initialize it again, and register the delegates again.
@MainActor
func restartRevue(with config: Revue.Configuration, delegate: RevueDelegate & RoomDelegate) async throws {
    await Revue.shared.destroy()
    try Revue.shared.initialize(config)

    Revue.shared.delegates.add(delegate: delegate)
    Room.shared.delegates.add(delegate: delegate)
}

Initialization and configuration¶

Initialize¶

Configuration¶

Start presence after sign-in¶

Destroy¶

Initialize again¶