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.3.3")}
Make sure to replace dev.yorkie
and 0.3.3
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.3.3</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, false, Options(apiKey = "xxxxxxxxxxxxxxxxxxxx"))// Declare your own CoroutineScopescope.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 CoroutineScopescope.launch {client.attachAsync(document).await()}
The created document should be attached to the client to automatically synchronize the document between the client and peers.
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 CoroutineScopescope.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 CoroutineScopescope.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 CoroutineScopescope.launch {document.collect { event ->println("A change event occured in the Document!")}}
You can execute different actions depending on the source of change.
// Declare your own CoroutineScopescope.launch {document.collect { event ->if (event is Document.Event.RemoteChange) {println("A peer has changed the Document!")}}}
To create a collaborative application, it is important to be able to access certain document properties when a specific property in the document is modified. By examining the paths
, you can determine which property has been changed and perform different actions based on that information.
// Declare your own CoroutineScopescope.launch {document.collect { event ->if (event is Document.Event.RemoteChange) {event.changeInfos.forEach { changeInfo ->changeInfo.paths.forEach { path ->if (path.startsWith("$.sharedMessage")) {println("One of your peers has changed the message to ${document.getRoot()["sharedMessage"]}")}}}}}}
6. Viewing the presence of other peers
Other peers' activities can be accessed by subscribing to the client.
// Declare your own CoroutineScopescope.launch {client.peerStatus.collect { peers ->println("There are currently ${peers.size} peers")}}
Next, let's take a look at the Android SDK.