Yorkie

Getting Started with iOS SDK

This guide walks you through the steps to get started with the Yorkie iOS SDK.

Using in your projects

Swift Package Manager

The Swift Package Manager is a tool for automating the distribution of Swift code and is integrated into the Swift compiler.

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.23")
]

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

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, _ in
  root.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, _ in
  root.sharedMessage = "Hello World!"
}
await print(self.document.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 in
  print("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.

The value can be: localChange, remoteChange or snapshot.

await doc.subscribe { event in
  if 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.subscribePresnece { event in 
  // get all users connected to the Document.
  let users = doc.getPresences() // [ (clientID: string, presence: [key: value]), ... ]
  print("There are currently \(users.count) users online")
}

Next, let's take a look at the iOS SDK.