Yorkie

Getting Started with Android SDK

Welcome to Yorkie Android SDK! In this guide, we will walk you through the steps to get started with the Android SDK.

Using in your projects

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

Gradle

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

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

Make sure to replace dev.yorkie and 0.4.7 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>0.4.7</version>
  <type>aar</type>
</dependency>

How to use Yorkie

1. Creating a Client with API key

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

val client = Client(context, "api.yorkie.dev", 443, Options(apiKey = "xxxxxxxxxxxxxxxxxxxx"))


// Declare your own CoroutineScope
scope.launch {
  client.activateAsync().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()
}

The document should be attached to the client in order to automatically synchronize it between the users participating the document.

3. Updating the Document

The created document is initially an empty object. You can create or update a key-value property you would like 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

If you want to access the document properties, you can 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 the changes that happen in the Document.

// 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 the presence of users participating in the document using doc.events.filterIsInstance<PresenceChange>(). You can use doc.presences to get the list of users who are currently involved in the document.

// Declare your own CoroutineScope
scope.launch {
  document.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.