본문으로 건너뛰기

Setup development

개발 환경 요구사항​

  • SDK : Android API 26 이상
  • JDK : JDK 11 이상
  • IDE : Android Studio
  • AVD : Connect SDK Emulator
정보

Connect SDK Emulator 설치에 대한 가이드는 Setup Connect SDK Emulator를 참조합니다.

프로젝트 설정​

SDK 의존성 설정​

  1. Project 수준 settings.gradle에 다음과 같이 추가합니다.
allprojects {
    repositories {
        google()
        mavenCentral()
        maven(url="https://nexus-playground.pleos.ai/repository/maven-releases")
    }
}
  1. App 수준 gradle file에 Sync SDK library 의존성을 추가합니다.
dependencies {
    // Add the dependency for the Sync SDK library
    implementation("ai.pleos.sync:syncSDK:2.3.0")
}

애플리케이션 권한 선언​

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>

초기화​

  1. SyncConfigsProvider를 생성합니다. SyncConfigsProvider는 프로젝트의 assets 폴더에 위치하고 있는 config 파일을 기반으로 연결 및 인증 정보를 구성합니다.
  2. initialize()를 이용하여 SyncDatabase를 초기화하며, 비동기 방식의 초기화를 위해 DatabaseListener를 등록할 수 있습니다.
  3. DatabaseListener가 실행된 후, InitializationState가 isReady 상태가 되면 SyncDatabase를 사용할 수 있습니다.
val configsProvider = SyncConfigsProvider.createFromConfigFile(applicationContext).getOrThrow()

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

Database 생성 요청

Playground > 상단 'My Project' > 프로젝트 선택 > 왼쪽 '프로젝트 정보' > 본문 하단 'Sync Database 관리' > Database 신청

정보

SyncConfigsProvider 사용 방법

Database를 신청한 후 설정(config) 파일을 다운로드하여, 프로젝트의 assets 폴더에 추가해 주세요. createFromConfigFile()에 의해 생성된 SyncConfigsProvider가 이를 읽어 적절한 연결 및 인증 정보를 구성합니다.

Document 가져오기​

Database에서 데이터를 읽고 쓰려면 SyncDatabase 인스턴스를 통해 document 객체를 생성해야 합니다. 이때, getInstance() 함수를 사용해야 하며, database 이름은 Playground에서 생성한 이름과 일치해야 합니다.

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

Database로부터 데이터 읽기​

Document의 value() helper 메소드를 통해 데이터를 읽을 수 있습니다. 예를 들어 데이터를 사용자 정의 구조체로 역직렬화하려면 다음과 같이 사용할 수 있습니다.

[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
      }
    ]
  }
}
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()

원격 데이터를 수신하거나 실시간 데이터를 처리하려면, addDocumentListener()를 통해 DocumentListener를 등록합니다.

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
    }
})

Database에 데이터 저장​

Document의 setKeyValue() 메소드를 통해 원하는 형태의 데이터를 추가 또는 수정할 수 있습니다.

//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
}

setKeyValue()의 key 값에 하위 노드 경로를 지정하면, 하위 노드의 데이터를 수정할 수 있습니다.

//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
}