If you want to update this page or add new content, please submit a pull request to the Homepage.

Getting Started with Android SDK

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

Prerequisite

  • Kotlin: 1.9.24 or higher
  • Android Gradle Plugin: 8.x or higher
  • minSdk: 24 or higher
  • Java: 17 or higher, for both the JDK and the Kotlin jvmTarget

Using in your projects

The library is published to Maven Central, so you can add the following line to your dependencies.

Gradle

To use the Yorkie Android SDK in your project, add it as a dependency in your build.gradle file.

dependencies {
implementation("dev.yorkie:yorkie-android:0.7.26")
}

Maven

Add a dependency to the <dependencies> element.

<dependency>
<groupId>dev.yorkie</groupId>
<artifactId>yorkie-android</artifactId>
<version>0.7.26</version>
<type>aar</type>
</dependency>

Android SDK v0.7.26 and later require a Yorkie server v0.7.26 or later. Since v0.7.26 each piece of text records the deletions that removed it and the undos that cancelled them, which keeps a Text undo converging through garbage collection, and the server stores that record with the document. The correctness rules shared with the server (tree node identity, how style attributes are stored, how a presence patch is stored, and this record of removals) mean you should upgrade every server node first and every client of a document together. Do not roll the server back once v0.7.26 clients are connected: a server older than v0.7.26 drops the record of removals when it re-encodes a document, so an undo that meets a concurrent deletion of the same text can leave clients disagreeing, and one older than v0.7.25 stores a presence patch that no client can read back, so every client fails the pulls that include it. Clients on v0.7.25 or earlier, of any SDK, can still disagree in that case. Presence patches and Watch stream heartbeats need server v0.7.25 or later; against an older server the SDK falls back to full presence updates and the old fixed stream timeout. Offline persistence and the stable actor need server v0.7.20 or later.

How to use Yorkie

1. Creating a Client with API key

First, create a Client instance with an API key and connect it to the Yorkie server.

val client = Client(
host = "https://api.yorkie.dev",
options = Client.Options(apiKey = "xxxxxxxxxxxxxxxxxxxx"),
)
// Declare your own CoroutineScope
scope.launch {
client.activateAsync().await()
}
// Do not forget to deactivate it when you no longer need it
scope.launch {
client.deactivateAsync().await()
}

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.

val document = Document("my-doc")
// Declare your own CoroutineScope
scope.launch {
client.attachDocument(document).await()
}
// Do not forget to detach it when you no longer need it
scope.launch {
client.detachDocument(document).await()
}

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

// Declare your own CoroutineScope
scope.launch {
document.updateAsync { root, _ ->
root["key"] = "value" // {"key":"value"}
}.await()
}

4. Accessing Document

To access document properties, use Document.getRoot().

// Declare your own CoroutineScope
scope.launch {
document.updateAsync { root, _ ->
root["sharedMessage"] = "Hello World!" // {"sharedMessage":"Hello World!"}
}.await()
println(document.getRoot()["sharedMessage"]) // "Hello World!"
}

5. Subscribing to the changes that happen in the Document

Clients sharing the same document can subscribe to changes.

// Declare your own CoroutineScope
scope.launch {
document.events.collect { event ->
println("A change event occurred in the Document!")
}
}

You can execute different actions depending on the source of change.

// Declare your own CoroutineScope
scope.launch {
document.events.collect { event ->
if (event is Document.Event.RemoteChange) {
println("A peer has changed the Document!")
}
}
}

6. Viewing the presence of other peers

You can also subscribe to user presence using document.events.filterIsInstance<Document.Event.PresenceChanged>(). Use document.presences to get the list of users currently participating in the document.

// Declare your own CoroutineScope
scope.launch {
document.events.filterIsInstance<Document.Event.PresenceChanged>().collect {
val users = document.presences.value
println("There are currently ${users.size} users online.")
}
}

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