Setup development

Development Environment Requirements

• SDK: Android API 26 or higher
• JDK: JDK 11 or higher
• IDE: Android Studio
• AVD: Pleos Connect Emulator

info

Refer to the guide on installing the Pleos Connect Emulator at Setup Pleos Connect Emulator.

Project Setup

SDK Dependency Setup

1. Add the following to the project-level settings.gradle.

settings.gradle.kts

allprojects {
    repositories {
        google()
        mavenCentral()
        maven(url="https://connect-nexus.developers.umos.ai/repository/maven-releases")
    }
}

settings.gradle

allprojects {
    repositories {
        google()
        mavenCentral()
        maven {
          url "https://connect-nexus.developers.umos.ai/repository/maven-releases"
        }
    }
}

2. Add Sync SDK library dependency to the app-level gradle file.

settings.gradle.kts

dependencies {
    // Add the dependency for the Sync SDK library
    implementation("ai.pleos.sync:syncSDK:2.1.0")
}

settings.gradle

dependencies {
    // Add the dependency for the Sync SDK library
    implementation 'ai.pleos.sync:syncSDK:2.1.0'
}

Application Permission Declaration

The following permissions are required to use the Sync SDK.

AndroidManifest.xml

<manifest>
    <uses-permission android:name="android.permission.INTERNET" />
    <uses-permission android:name="android.permission.GET_ACCOUNTS" />
    <uses-permission android:name="pleos.car.permission.SYNC_DATA" />
</manifest>

Initialization

1. Create SyncConfigsProvider. SyncConfigsProvider configures connection and authentication information based on the config file located in the project's assets folder.
2. Initialize SyncDatabase using initialize(), and register DatabaseListener for asynchronous initialization.
3. Once DatabaseListener executes and InitializationState becomes isReady, you can use SyncDatabase.

Kotlin

val configsProvider = SyncConfigsProvider.createFromConfigFile(applicationContext).getOrThrow()

SyncDatabase.initialize(application, configsProvider) {
    if (it.isReady()) { 
        syncDatabase = SyncDatabase.getInstance("databaseName")
    } else {
        //TODO: handle failure
    }
}

Java

SyncConfigsProvider configsProvider = SyncConfigsProvider.createFromConfigFile(applicationContext).getOrThrow();

SyncDatabase.initialize(application, configsProvider, new InitializationCallback() {
    @Override
    public void onInitialized(InitializationState state) {
        if (state.isReady()) {
            syncDatabase = SyncDatabase.getInstance("databaseName");
        } else {
            // TODO: handle failure
        }
    }
});

info

Database 생성 요청

Playground > Select Project > API & SDK > Sync SDK > Apply for database

info

SyncConfigsProvider 사용 방법

After applying for the database, download the configuration file and add it to the project's assets folder. Place the downloaded configuration file in the assets folder of the project.
SyncConfigsProvider created using createFromConfigFile() reads it and configures appropriate connection and authentication information.

Fetching Document

To read and write data in the database, you need to create a document object through a SyncDatabase instance. At this time, you must use the getInstance() function, and the database name must match the name created in Playground.

Kotlin

val database = SyncDatabase.getInstance("databaseName")
val document = syncDatabase.document("documentName")

Java

SyncDatabase database = SyncDatabase.getInstance("databaseName")
SyncDocument document = database.document("documentName")

Reading Data from the Database

Data can be read using the value() helper method of the Document. For example, to deserialize data into a custom structure, you can use it as follows.

[Document data]

{
  "name": "developer",
  "age": 20,
  "isMale": true,
  "company": {
    "name": "42dot",
    "address": "anywhere on earth",
    "wanted": [
      {
        "role": "Front-end",
        "count": 10
      },
      {
        "role": "Back-end",
        "count": 10
      }
    ]
  }
}

Kotlin

data class Wanted(val role:String, val count:Int)
data class Company(val name:String, val address:String, val wanted:List<Wanted>?)
data class FullUserProfile(val name:String, val age: Int, val isMale: Boolean, val company:Company?)

val fullProfile: FullUserProfile? = appDoc?.value()

Java

public class FullUserProfile {
    public String name;
    public int age;
    public boolean isMale;
    public Company company;
    
    public static class Wanted {
        public String role;
        public int count;
    }

    public static class Company {
        public String name;
        public String address;
        public List<Wanted> wanted;
    }
}

Optional<FullUserProfile> fullProfile = Optional.ofNullable(appDoc.value(FullUserProfile.class));

To receive remote data or handle real-time data, register a DocumentListener using addDocumentListener().

Kotlin

appDoc.addDocumentListener(listener : DocumentListener {
    override fun onDocumentChanged(document: SyncDocument, fromRemote: Boolean) {
        val fullProfile: FullUserProfile? = document.value()
        println("latest user profile : $fullProfile") 
    }

    override fun onDocumentError(document: SyncDocument, err: SyncError) {
        // TODO: Handle data sync error
    }
})

Java

appDoc.addDocumentListener(new DocumentListener() {
    @Override
    public void onDocumentChanged(@NonNull SyncDocument document, boolean fromRemote) {
        Optional<FullUserProfile> fullProfile = Optional.ofNullable(document.value(FullUserProfile.class));
        Log.d(TAG, String.format("latest user profile :", fullProfile)); 
    }

    @Override
    public void onDocumentError(@NonNull SyncDocument document, @NonNull SyncError e) {
        // TODO: Handle data sync error
    }
})

Saving Data to the Database

You can add or modify data in the desired format through the Document's setKeyValue() method.

Kotlin

//Update field value
appDoc?.setKeyValue("Mr.Famous", "name")?.onFailure { e ->
   //TODO: handle error
}
//Insert a new field
appDoc?.setKeyValue("I'm a newbie", "new")?.onFailure { e ->
   //TODO: handle error
}
//Insert a new object
appDoc?.setKeyValue(mapOf("hello" to "world"), "newObject")?.onFailure { e ->
   //TODO: handle error
}
//Insert a new array
appDoc?.setKeyValue(listOf(1, 2, 3), "newArray")?.onFailure { e ->
   //TODO: handle error
}

Java

//Update field value
appDoc.setKeyValue("Mr.Famous", "name").onFailure(e -> {
   //TODO: handle error
})
//Insert a new field
appDoc.setKeyValue("I'm a newbie", "new").onFailure(e -> {
   //TODO: handle error
})
//Insert a new object
appDoc.setKeyValue(Collections.singletonMap("hello", "world"), "newObject").onFailure(e -> {
   //TODO: handle error
})
//Insert a new array
appDoc.setKeyValue(Arrays.asList(1, 2, 3), "newArray").onFailure(e -> {
   //TODO: handle error
})

If you specify the path of the subnode in the key of setKeyValue(), you can modify the data of the subnode.

Kotlin

//Update field value
appDoc?.setKeyValue("NewCompany", "company.name")?.onFailure { e ->
   //TODO: handle error
}
//Insert a new field
appDoc?.setKeyValue(2019, "company.since")?.onFailure { e ->
   //TODO: handle error
}

Java

//Update field value
appDoc.setKeyValue("NewCompany", "company.name").onFailure(e -> {
   //TODO: handle error
})
//Insert a new field
appDoc.setKeyValue(2019, "company.since").onFailure(e -> {
   //TODO: handle error
})