with-android-sdk.mdx

title	order
with Android SDK	24

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

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:{{YORKIE_ANDROID_VERSION}}")
}

Make sure to replace dev.yorkie and {{YORKIE_ANDROID_VERSION}} with the correct group ID and version number for the Yorkie SDK.

Maven

Add a dependency to the <dependencies> element.

<dependency>
  <groupId>dev.yorkie</groupId>
  <artifactId>yorkie-android</artifactId>
  <version>{{YORKIE_ANDROID_VERSION}}</version>
  <type>aar</type>
</dependency>

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 = "{{API_ADDR}}",
  options = 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(Key("my-doc"))

// Declare your own CoroutineScope
scope.launch {
  client.attachAsync(document).await()
}

// Do not forget to detach it when you no longer need it
scope.launch {
  client.detachAsync(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 doc.events.filterIsInstance<PresenceChange>(). Use doc.presences to get the list of users currently participating in the document.

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

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