If you want to update this page or add new content, please submit a pull request to the Homepage.
Getting Started with iOS SDK
This guide walks you through the steps to get started with the Yorkie iOS SDK.
Using in your projects
The iOS SDK supports iOS 15 or later and macOS 13 or later.
Swift Package Manager
The Swift Package Manager is a tool for automating the distribution of Swift code and is integrated into the Swift compiler.
In Xcode, choose File > Add Package Dependencies..., enter https://github.com/yorkie-team/yorkie-ios-sdk.git, and add the Yorkie library to your app target.
Once you have your Swift package set up, add Yorkie as a dependency in the dependencies section of your Package.swift.
dependencies: [.package(url: "https://github.com/yorkie-team/yorkie-ios-sdk.git", from: "0.7.26")],targets: [.target(name: "MyApp",dependencies: [.product(name: "Yorkie", package: "yorkie-ios-sdk")])]
The package also ships YorkieDevtoolsUI and YorkieDevtoolsServer libraries for inspecting documents during development; add them the same way if you need them.
iOS SDK v0.7.26 and later require a Yorkie server v0.7.26 or later. Several of the SDK's correctness rules — tree node identity, element identity in garbage collection and when a tombstone may be collected, the checkpoint an offline resume re-anchors against, how style attributes are stored and sized, how presence is sent as a patch, and the record of removals that keeps a Text undo converging through garbage collection — are part of the wire contract shared with the server, so an older server can abort a sync rather than degrading. Watch stream heartbeats also need a v0.7.25 server. Upgrade every server node first, and do not roll the server back once v0.7.26 clients are connected: a server older than v0.7.26 drops that record of removals when it re-encodes a document, and one older than v0.7.25 stores a presence patch that no client can read back. Since v0.7.26 a piece of text removed by two concurrent deletions that nobody undoes is kept rather than collected, and counts toward the document size limit. Upgrade every client of a document together: since v0.7.23 a plain string style value is sent as itself (red, not "red"), which an older iOS client does not render. On a server older than v0.7.16, a JSONTree undo or redo aborts with ErrInvalidArgument: offset out of range.
How to use Yorkie
1. Creating a Client with API key
First, create a Client with an API key.
let client = Client("https://api.yorkie.dev", ClientOptions(apiKey: "xxxxxxxxxxxxxxxxxxxx"))try await client.activate()
The API key is used to identify the project in Yorkie. You can get the API key of the project you created in the Dashboard.
2. Creating a Document
Then create a Document.
let doc = Document(key: docKey)try await client.attach(doc, [:])
Attach the document to the client to automatically synchronize it between users participating in the document.
3. Updating the Document
The document is initially an empty object. You can create or update key-value properties to share with peers using Document.update().
try await doc.update{ root, _ inroot.todos = Array<String>() // {"todos":[]}(root.todos as? JSONArray)?.append("todo-1") // {"todos":["todo-1"]}root.obj = ["name": "yorkie", "age": Int64(14)] // {"obj":{"name":"yorkie","age":14},"todos":["todo-1"]}}
4. Accessing Document
To access document properties, use doc.getRoot(). With dot notation, you can access any key-value property that you or your peers have set.
try await doc.update{ root, _ inroot.sharedMessage = "Hello World!"}print(doc.getRoot().sharedMessage!) // "Hello World!"
5. Subscribing to the changes that happen in the Document
Clients sharing the same document can subscribe to changes using doc.subscribe().
await doc.subscribe { event, _ inprint("A change event occurred in the Document!")}
You can execute different actions depending on the source of change. The source can be accessed from event.type.
For content changes, the value can be: localChange, remoteChange or snapshot. Other event types, such as connection and sync status, are covered in the iOS SDK reference.
await doc.subscribe { event, _ inif event.type == .remoteChange {print("A peer has changed the Document!")}}
6. Viewing the presence of users
You can also subscribe to user presence using doc.subscribePresence(.presence). Use doc.getPresences() to get the list of users currently participating in the document.
await doc.subscribePresence { event, doc in// get all users connected to the Document.let users = doc.getPresences() // [(clientID: ActorID, presence: [String: Any]), ...]print("There are currently \(users.count) users online")}
Next, let's take a look at the iOS SDK.