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.

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()

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.

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)

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

// let's say 'color' is a property of cursor
try await client.attach(doc, ["cursor": ["x": 0, "y": 0, "color": "red"]])

try await doc.update { root, presence in 
  // we want to change the x y coordinates of our cursor
    presence.set(["cursor": ["x": 1, "y": 1]])
}

// final state
// presence = { cursor: { x: 1, y: 1 } } 
// we can see that all properties inside cursor get replaced (i.e. we lose the property 'color')

Getting presence

You can get the presences of the current client and other clients participating in the document.

Document.getPresence(clientID)

It returns the presence of a specific client.

await doc.getPresence(client.id!) // ["color": "blue", "cursor": ["x": 1, "y": 1]]

Document.getMyPresence()

It returns the presence of the current client that has attached to the document.

await doc.getMyPresence() // ["color": "blue", "cursor": ["x": 1, "y": 1]]

Document.getPresences()

It returns an array about all clients currently participating in the document. Each entry in the array includes the client's id and presence.

let users = await doc.getPresences()
for (clientID, presence) in users {
    // Do somethins
}

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: localChange, remoteChange, or snapshot.

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
            }
        }
    }
}

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.

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.

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.

Reference

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