Yorkie

iOS SDK

Through Yorkie iOS SDK, you can efficiently build collaborative applications. On the client-side implementation, you can create Documents that are automatically synced with remote peers with minimal effort.

If you want to install the SDK, refer to the Getting Started with iOS SDK.

Client

Client is a normal client that can communicate with the server. It has Documents and sends changes of the Document from local to the server to synchronize with other replicas remotely. For more information about Client, please refer to the Client.

Creating a Client

We can create a Client using Client(). After the Client has been activated, it is connected to the server and ready to use.

let client = Client("https://api.yorkie.dev", ClientOptions(
    apiKey: "xxxxxxxxxxxxxxxxxxxx"
))
try await client.activate()

let client = Client("http://localhost:{{port}}")
try await client.activate()

For more information about CLI, please refer to the CLI.

Creating a Client with Auth Token

You can configure authentication for the client by setting up an authTokenInjector to provide tokens for Auth Webhook verification. If a codes.Unauthenticated error occurs, the authTokenInjector will be called again with the webhook's response reason, enabling automatic token refresh. For more information about Auth Webhook, please refer to the Auth Webhook.

struct MyAuthTokenInjector: AuthTokenInjector {
    func getToken(reason: String?) async throws -> String {
        if reason == "token expired" {
            return await refreshAccessToken()
        }
        return accessToken
    }
}

let client = Client("https://api.yorkie.dev", ClientOptions(apiKey: "xxxxxxxxxxxxxxxxxxxx", authTokenInjector: MyAuthTokenInjector()))

Syncing Documents if needed

In SyncMode.manual, the client does not automatically synchronize documents with the server. Therefore, you need to manually call the sync(document:) method to synchronize the document when necessary.

try await client.sync(doc)

Deactivate the Client

When the client is no longer needed, you can deactivate it to release resources and disconnect from the server.

try await client.deactivate()

This will detach all documents attached to the client for efficient garbage collection.

Document

Document is a primary data type in Yorkie, which provides a JSON-like updating experience that makes it easy to represent your application's model. A Document can be updated without being attached to the client, and its changes are automatically propagated to other clients when the Document is attached to the Client or when the network is restored.

For more information about Document, please refer to the Document.

Creating a Document

You can create a Document using Document(key:). Let's create a Document with a key and attach it to the Client.

let doc = Document(key: "doc-1")

Attaching the Document

When you attach, the client notifies the server that it is subscribing to this document. If the document does not exist on the server, it will be created, and any local changes that occurred will be updated to the server's document. If the server already has a document associated with the provided key, it sends the existing changes to the client, which are then applied to synchronize the document.

Once attached, the document becomes synchronized with other clients. This ensures that any modifications made by one client are instantly propagated to other clients collaborating on the same document.

The second argument is options.

• initialPresence: Sets the initial presence of the client that attaches the document. The presence is shared with other users participating in the document. It must be serializable to JSON.
• syncMode(Optional): Specifies synchronization modes. The default value is SyncMode.realtime, which automatically pushes and pulls changes. If you set it to SyncMode.manual, you'll need to manually handle synchronization.

try await clientA.attach(doc, ["color": "blue", "cursor": ["x": 0, "y": 0]], .manual)

Initializing root

The root is used to manage the application's data, such as primitives, arrays, Counters, and Text in a form within the Document. You can set the initial values when calling Document.attach() using the initialRoot option.

try await client.attach(doc, initialRoot: [
    "list": [Int32(1), Int32(2), Int32(3)]
])

The initial values are partially applied. For each element in initialRoot:

• If the key doesn't exist, the element will be applied.
• If the key already exists in the Document, that element will be discarded. Users don't need to worry about overwriting existing valid counters.

// Another client tries to attach with initialRoot option:
try await client2.attach(doc, initialRoot: [
    "list": [],                                  // this update will be discarded
    "counter": JSONCounter(value: Int32(0))      // this update will be applied
])

// final state
// root = {
//   list: [1, 2, 3],
//   counter: 0
// }

We support element types for Primitives, and Custom CRDT types.

Updating presence

The Document.update() method allows you to make changes to the state of the current user's presence.

Specific properties provided will be changed. The existing presence object will be updated by merging the new changes. In other words, properties not specified in the update function will remain unchanged.

try await doc.update { root, presence in
  presence.set(["cursor": ["x": 1, "y": 1]])
}
// final state
// presence = { color: 'blue', cursor: { x: 1, y: 1 } }
// we can see that the changes made were merged and the final state of the current user's presence is as we desire

// ❌ This loses the 'color' property
presence.set(["cursor": ["x": 1, "y": 1]])

// ✅ This preserves all properties
presence.set(["cursor": ["x": 1, "y": 1, "color": "red"]])

Getting presence

You can retrieve presence information for clients participating in the document.

Getting specific client presence:

await doc.getPresence(client.id!)

Getting your own presence:

await doc.getMyPresence()

Getting all presences:

let users = await doc.getPresences()

Document.subscribePresence(.presence)

This method allows you to subscribe to presence-related changes. You'll be notified whenever clients watch, unwatch, or modify their presence.

The initialized event occurs when the client list needs to be initialized. For example, this happens when you first connect a watch stream to a document, when the connection is lost, or when it is reconnected.

await doc.subscribePresence { event in
    if event.type == .initialized {
        // Array of other users currently participating in the document
        // event.value;
    }
    
    if event.type == .watched {
        // A user has joined the document editing in online
        // event.value;
    }
    
    if event.type == .unwatched {
        // A user has left the document editing
        // event.value;
    }
    
    if event.type == .presenceChanged {
        // A user has updated their presence
        // event.value;
    }
}

Use .myPresence and .others topics to distinguish between your own events and those of others.

Document.subscribePresence(.myPresence)

This method is specifically for subscribing to changes in the presence of the current client that has attached to the document.

The possible event.type are: initialized, presenceChanged.

await doc.subscribePresence(.myPresence) { event in
    // Do something
}

Document.subscribePresence(.others)

This method enables you to subscribe to changes in the presence of other clients participating in the document.

The possible event.type are: watched, unwatched, presenceChanged.

await doc.subscribePresence(.others) { event in
    if event.type == .watched {
        addUser(event.value)
    }
    
    if event.type == .unwatched {
        removeUser(event.value)
    }

    if event.type == .presenceChanged {
        updateUser(event.value)
    }
}

Editing the Document

Document.update(:,message:) enables you to modify a Document. The optional message allows you to add a description to the change. If the Document is attached to the Client, all changes are automatically synchronized with other Clients.

let message = "update document for test";
try await doc.update({ root, _ in
  root.todos = Array<String>()
  (root.todos as? JSONArray)?.append("todo-1")
  root.obj = ["name": "yorkie", "age": Int64(14)]
  root.counter = JSONCounter(Int64(0))
  (root.counter as? JSONCounter<Int64>)?.increase(1)
}, message: message);

Under the hood, root in the update function creates a change, a set of operations, using a JavaScript proxy. Every element has its unique ID, created by the logical clock. This ID is used by Yorkie to track which object is which.

You can get the contents of the Document using doc.getRoot().

let root = doc.getRoot()
print(root.todos!)                      // Optional(["todo-1"])
print(root.obj!)                        // {"name":"yorkie","age":14}
print((root.obj as! JSONObject).name!)  // yorkie
print(root.counter!)                    // 1

Subscribing to Document

You can subscribe to various events occurring in the Document, such as changes, connection status, synchronization status, and all events by using the document.subscribe() method. By subscribing to these events, you can update the UI in real-time and handle exceptions that may occur during synchronization.

Document.subscribe()

A Document can be modified by changes generated remotely or locally in Yorkie. Whenever the Document is modified, change events are triggered and you can subscribe to these events using the document.subscribe(callback) method. By subscribing to changes in the Document, you can receive updates in real-time, which is useful for updating the UI when the Document changes.

The callback is called with an event object, and the event.type property indicates the source of the change, which can be one of the following values: statusChanged, connectionChanged, syncStatusChanged, snapshot, localChange, remoteChange, initialized, watched, unwatched, presenceChanged, broadcast, localBroadcast or authError.

For more information about document events, please refer to the DocEvent.

await self.document.subscribe { event, _ in
    if event.type == .snapshot {
        // `snapshot` delivered when the entire document is updated from the server.
    } else if event.type == .localChange {
        // `local-change` delivered when calling document.update from the current client.
    } else if let event = event as? RemoteChangeEvent {
        // `remote-change` delivered when the document is updated from other clients.
        let changeInfo = event.value
        
        // You can access the operations that have been applied to the document.
        changeInfo.operations.forEach { op in
            // e.g.) { type: 'increase', value: 1, path: '$.counter' }
            switch (op.type) {
            case .increase:
                // ...
                break
            default:
                break
            }
        }
    } else {
        // others case...
    }
}

When the event.type is localChange or remoteChange, the event.value is a changeInfo, which has operations and message properties. For more information about changeInfo for document events, please refer to the ChangeInfo.

The snapshot event is triggered when a snapshot is received from the server. This occurs when the changes that a document needs to fetch from the server exceed a certain SnapshotThreshold. Instead of sending numerous changes, the server sends a snapshot of the document. In such cases, it is essential to update with data from the Yorkie Document.

The available Event Types are:

Document.subscribe("$.path")

Additionally, you can subscribe to changes for a specific path in the Document using doc.subscribe(targetPath, callback) with a path argument, such as $.todos, where the $ sign indicates the root of the document. The callback function is called when the target path and its nested values are changed.

With this feature, you can easily subscribe to changes for a specific part of the document and perform different actions based on the updated values.

await doc.subscribe("$.todos") { event in 
  // The callback will be called when the root.todos or its nested values change.
  Task {
    let target = try? await target.getValueByPath(path: "$.todos") // You can get the value by path.
  }
  // Do something...
}

Document.subscribeConnection()

After attaching the document to the client, the document is continuously synchronized with the server in real-time. This is achieved by maintaining a watch stream connection between the client and the server, which allows the client to receive events and updates from other users.

To monitor the connection status of the stream, you can use a callback function that is triggered whenever the connection status changes. The possible values for event.value are StreamConnectionStatus.connected and StreamConnectionStatus.disconnected.

When the watch stream is disconnected, it indicates that the user is offline and will not receive real-time updates from other users.

await self.document.subscribeConnection { event, _ in
    let event = event as! ConnectionChangedEvent
    if event.value == .connected {
        // The watch stream is connected.
    } else if event.value == .disconnected {
        // The watch stream is disconnected.
    }
}

For more information about StreamConnectionStatus, please refer to the StreamConnectionStatus.

Document.subscribeSync()

If the document is attached to the client in SyncMode.realtime, the document is automatically synchronized with the server in real-time. Under this mode, the document executes synchronization in the background, and you can track the synchronization status using the sync event. The possible event.value values are: DocumentSyncStatus.synced and DocumentSyncStatus.syncFailed.

await self.document.subscribeSync { event, _ in
    let event = event as! SyncStatusChangedEvent
    if event.value == .synced {
        // The document is synchronized with the server.
    } else if event.value == .syncFailed {
        // The document failed to synchronize with the server.
    }
}

For more information about DocumentSyncStatus, please refer to the DocumentSyncStatus.

Document.subscribeAuthError()

You can subscribe to authentication error events using doc.subscribeAuthError(). This event is triggered when an unauthenticated error occurs during PushPull or WatchDocuments operations, specifically when the system automatically refreshes the token and retries the operation.

await doc.subscribeAuthError { event, _ in
    guard let authErrorEvent = event as? AuthErrorEvent else { return }
    // authErrorEvent.value contains:
    // - reason: string
    // - method: 'PushPull' | 'WatchDocuments'
}

This subscription allows you to monitor when token refreshes occur due to authentication errors.
For more information about Auth Webhook, please refer to the Auth Webhook.

Broadcasting a Message

Broadcasting allows clients to share custom events with other clients connected to the same document. Unlike document updates or presence changes, broadcasts are ephemeral messages that are not persisted in the document's state.

// Step 1: Define your message structure
let payload = Payload(["message": "Hello!"])

// Step 2: Broadcast to topic
try await doc.broadcast(topic: "chat", payload: payload)

// Step 3: Subscribe and handle
try await doc.subscribeBroadcast { event, _ in
    guard let event = event as? BroadcastEvent else { return }
    print("Received: \(event.value.payload["message"] ?? "")")
}

The broadcast event contains:

• topic: A string identifying the type of broadcast message
• payload: The data being broadcast (must be JSON serializable)
• clientID: The ID of the client that sent the broadcast

This feature is useful for sending temporary messages or signals between clients, such as:

• Chat messages
• Cursor movement notifications
• Application-specific events
• User action notifications

Changing Synchronization Mode

To change the synchronization mode for a document, you can use client.changeSyncMode(doc, syncMode).

Yorkie offers four SyncModes:

• SyncMode.realtime: Local changes are automatically pushed to the server, and remote changes are pulled from the server.

• SyncMode.realtimePushOnly: Only local changes are pushed, and remote changes are not pulled.

• SyncMode.realtimeSyncOff: Changes are not synchronized, but the watch stream remains active.

• SyncMode.manual: Synchronization no longer occurs in real-time, and the watch stream is disconneted. Manual handling is required for synchronization.

// Enable automatic synchronization of both local and remote changes.
try await client.changeSyncMode(doc, realtime)

// Only push local changes automatically.
try await client.changeSyncMode(doc, .realtimePushOnly)

// Synchronization turned off, but the watch stream remains active.
try await client.changeSyncMode(doc, .realtimeSyncOff)

// Synchronization turned off, and the watch stream is disconneted.
try await client.changeSyncMode(doc, manual)
try await client.sync(doc) // Trigger synchronization manually using the sync function.

Detaching the Document

If the document is no longer used, it should be detached to increase the efficiency of GC removing CRDT tombstones. For more information about GC, please refer to Garbage Collection.

try await client.detach(doc)

Custom CRDT types

Custom CRDT types are data types that can be used for special applications such as text editors and counters, unlike general JSON data types such as JSONObject and JSONArray. Custom CRDT types can be created in the callback function of document.update.

JSONText

JSONText provides supports for collaborative text editing. In addition, contents in JSONText can have attributes; for example, characters can be bold, italic, or underlined.

try await doc.update{ root in
    root.text = JSONText() // {"text":[]}
    (root.text as? JSONText)?.edit(0, 0, "hello")               // {"text":[{"val":"hello"}]}
    (root.text as? JSONText)?.edit(0, 1, "H")                   // {"text":[{"val":"H"},{"val":"ello"}]}
    (root.text as? JSONText)?.setStyle(fromIdx: 0, toIdx: 1, attributes: ["bold": true])    // {"text":[{"attrs":{"bold":"true"},"val":"H"},{"val":"ello"}]}
}

Selection using presence

The temporary client information, such as text selection, does not need to be stored in the document permanently. Instead, it can be effectively shared using presence.

When transmitting text selection information, it is essential to convert the index, which can vary based on the text state, into the position used by Yorkie.JSONText. This converted position selection can then be sent and applied through presence.

Here is an example where presence is used to share text selection between users in UITextView.

• When the text selection is changed:

let range: NSRange  // eg. selected range converted from selectedTextRange of UITextView

let fromIdx = range.location
let toIdx = range.location + range.length

try await doc.update { root, presence in
    if let range = try? (root.content as? JSONText)?.indexRangeToPosRange((fromIdx, toIdx)) {
        presence.set(["from": range.0, "to": range.1])
    }
}

• When applying other user's selection changes:

await doc.subscribePresence(.others) { event in 
    if let event = event as? PresenceChangedEvent {
        if let fromPos: TextPosStruct = decodePresence(event.value["from"]),
            let toPos: TextPosStruct = decodePresence(event.value["to"]) {
            if let (fromIdx, toIdx) = try? await(document.getRoot().content as? JSONText)?.posRangeToIndexRange((fromPos, toPos)) {
                // Handle the updated selection in the editor
            }
        }
    }
}

private func decodePresence<T: Decodable>(_ dictionary: Any?) -> T? {
    guard let dictionary = dictionary as? [String: Any],
            let data = try? JSONSerialization.data(withJSONObject: dictionary, options: [])
    else {
        return nil
    }

    return try? JSONDecoder().decode(T.self, from: data)
}

Text selection can be efficiently shared using presence. Please refer to the following example for a complete code:

An example of Text Editor: Text Editor example

JSONCounter

JSONCounter supports integer types changing with addition and subtraction. If an integer data needs to be modified simultaneously, JSONCounter should be used instead of primitives.

try await doc.update{ root in
    root.counter = JSONCounter(value: Int64(1))                 // {"counter":1}
    (root.counter as? JSONCounter<Int64>)?.increase(value: 2)   // {"counter":3}
    (root.counter as? JSONCounter<Int64>)?.increase(value: 3)   // {"counter":6}
    (root.counter as? JSONCounter<Int64>)?.increase(value: -4)  // {"counter":2}
}

Logger Options

The Logger outputs events occurring within the SDK to the console for debugging purposes. To modify these options, you can use the Logger.logLevel variable.

Logger.logLevel = .error

The available log levels for setLogLevel are:

Adjust the log level for flexible control over log verbosity in your application.

Performance Best Practices

• Use SyncMode.realtimePushOnly for write-heavy operations
• Batch updates within single doc.update() call
• Detach documents when switching contexts
• Use Logger.logLevel = .error in production

Common Use Cases

Real-time Collaborative Text Editing

// Initialize text
try await doc.update { root, _ in
    root.content = JSONText()
}

// Handle text changes
try await doc.update { root, presence in
    (root.content as? JSONText)?.edit(0, 0, "Hello")
    
    // Share cursor position
    if let range = try? (root.content as? JSONText)?.indexRangeToPosRange((0, 5)) {
        presence.set(["selection": ["from": range.0, "to": range.1]])
    }
}

Shared Counter

try await doc.update { root, _ in
    root.likes = JSONCounter(value: Int64(0))
}

// Increment likes
try await doc.update { root, _ in
    (root.likes as? JSONCounter<Int64>)?.increase(value: 1)
}

Live Cursor Tracking

// Update cursor position
try await doc.update { root, presence in
    presence.set(["cursor": ["x": 100, "y": 200]])
}

// Subscribe to others' cursors
await doc.subscribePresence(.others) { event in
    if event.type == .presenceChanged {
        // Update UI with new cursor positions
    }
}

Troubleshooting

Document Not Syncing

• Verify SyncMode is set to .realtime
• Check network connection using subscribeConnection()
• Ensure client is properly activated

Presence Not Updating

• Subscribe to presence events before attaching document
• Verify presence data is JSON serializable
• Check that document is attached to client

Memory Issues

• Detach unused documents
• Set appropriate Logger.logLevel
• Monitor document size and consider splitting large documents

Reference

For details on how to use the iOS SDK, please refer to iOS SDK Reference.