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 in remote.
Creating a Client
We can create a Client using Client(rpcAddress: RPCAddress(host:,port:), options:)
. After the Client has been activated, it is connected to the server and ready to use.
let client = Client(rpcAddress: RPCAddress(host: "api.yorkie.dev", port: 443), options: ClientOptions(apiKey: "xxxxxxxxxxxxxxxxxxxx"))try await client.activate()
Subscribing to Client events
We can use client.eventStream
to subscribe to client-based events, such as status-changed
, stream-connection-status-changed
and peer-changed
.
target.eventStream.sink { event inswitch event.type {case .statusChanged:()case .streamConnectionStatusChanged:()default:break}}
By using the value of the stream-connection-status-changed
event, it is possible to determine whether the Client is connected to the network.
If you want to know about other ClientEvents, please refer to the ClientEventType.
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 peers when the Document is attached to the Client or when the network is restored.
Creating a Document
We can create a Document using Document(key: "doc-key")
. Let's create a Document with a key and attach it to the Client.
let doc = Document(key: docKey)await client.attach(doc);
After attaching the Document to the Client, all changes to the Document are automatically synchronized with remote peers.
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";await doc.update({ root inroot.obj = [:] // {"obj":{}}let obj = root.obj as! JSONObjectobj.num = Int64(1) // {"obj":{"num":1}}obj.obj = ["str": "a"] // {"obj":{"num":1,"obj":{"str":"a"}}}obj.arr = [Int64(1), Int64(2)] // {"obj":{"num":1,"obj":{"str":"a"},"arr":[1,2]}}}, 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.obj!) // {"num":1,"obj":{"str":"a"},"arr":[1,2]}let obj = root.obj as! JSONObjectprint(obj.num!) // 1print(obj.obj!) // {"str":"a"}print(obj.arr!) // [1,2]
Subscribing to Document events
A Document is modified by changes generated remotely or locally in Yorkie. When the Document is modified, change events occur, to which we can subscribe using document.subscribe
. Here, we can do post-processing such as repaint in the application using the path
of the change events.
await target.eventStream.sink { event inswitch event {case let event as LocalChangeEvent:print(event)case let event as RemoteChangeEvent:for changeInfo in event.value {print(changeInfo.change.message)for path in changeInfo.paths {if path.starts(with: "$.obj.num") {// root.obj.num is changed} else if path.starts(with: "$.obj") {// root.obj is changed}}}}}
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. JSONText
has selection information for sharing the cursor position. In addition, contents in Text
can have attributes; for example, characters can be bold, italic, or underlined.
await doc.update{ root inroot.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)?.select(0, 1)(root.text as? JSONText)?.setStyle(fromIdx: 0, toIdx: 1, attributes: ["bold": true]) // {"text":[{"attrs":{"bold":"true"},"val":"H"},{"val":"ello"}]}}
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.
await doc.update{ root inroot.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}}
Reference
For details on how to use the iOS SDK, please refer to iOS SDK Reference.