アプリに Device Sync を追加する - Kotlin SDK

デバイスの同期

Device Syncは、クライアント デバイスと Atlas 間でデータを同期します。 オフラインでもデバイス上にデータは保持されます。 デバイスがネットワークに接続している場合、Device Sync はバックグラウンドでデータをアップロードおよびダウンロードし、競合の解決を管理します。

クライアント アプリと Atlas 間で同期されるデータは、適格なデータにアクセスするためのユーザーの権限によって決まります。 適格なデータは、次の共通部分です。

• データモデル: データ型情報

• サブスクリプション クエリ: 保存するデータを定義する条件

• 権限: 指定された条件を満たすデータを操作するために必要なロールベースの権限

Device Sync の詳細については、Atlas App Services ドキュメントの「 Atlas Device Sync を使い始める 」を参照してください。

前提条件

アプリに Device Sync を追加するには、アプリの状態とデータに応じて、いくつかの方法があります。 このガイドでは、開発モードを使用して既存のクライアント アプリに同期を追加する方法について説明します。 このガイドでは、アプリが Realm Kotlin SDK を使用しており、クライアント コードでデータモデルをすでに定義していることを前提としています。

Device Sync は Atlas App Services App を介してクライアント アプリを App Services バックエンドに接続するため、開始する前に次の操作を行う必要があります。

1. 認証が有効になっている Atlas App Services App その方法については、App Services ドキュメントの「 App App Services Appの作成」を参照してください。

2. アプリが App Services バックエンドに接続できることを確認します。 方法については、「 Atlas App Services への接続 - Kotlin SDK 」を参照してください。

このページの例について

このページの例は、 Itemオブジェクトのリストを含む Listオブジェクトを含むすでに定義されたデータモデルを持つ Kotlin Todo アプリの例を参照しています。

class List : RealmObject {
    @PrimaryKey
    var _id: ObjectId = ObjectId()
    var name: String = ""
    var ownerId: String = ""
    var items: RealmList<Item> = realmListOf()
}
class Item : RealmObject {
    @PrimaryKey
    var _id: ObjectId = ObjectId()
    var name: String = ""
    var complete: Boolean = false
}

App Services での Device Sync の有効化

クライアントアプリに同期を追加する前に、まず Atlas App Services アプリで Device Sync を有効にする必要があります。

アプリで Device Sync を有効にするには、App Services ドキュメントの「 Atlas Device Sync の構成と有効化」手順で説明されている手順を実行します。

このプロセス中に、開発モードを有効にするかどうかを選択でき、アプリユーザーのデフォルトロールを選択できます。 利用可能な設定の詳細については、App Services ドキュメントの「 同期設定」を参照してください。

このサンプルアプリでは、開発モードで Device Sync を有効にし、デフォルトの「ユーザーはすべてのデータの読み取りと書込みができる」デフォルトロールを追加しています。 つまり、ネットワーク接続を持つ承認されたユーザーの場合、Device Sync は適切なデータをクライアントにダウンロードし、 Atlas はクライアントへの書込みを許可し、それらをバックエンドと同期します。 承認されたユーザーがネットワークに接続していない場合にどのような影響があるかについて詳しくは、「書き込みの考慮事項 」を参照してください。

クライアント アプリへの同期の追加

Atlas App Services で同期を設定して有効にしたら、クライアント アプリに同期を追加できます。

// Replace `YOUR_APP_ID` with your Atlas App ID
val app = App.create(YOUR_APP_ID)

// Authenticate the Atlas App Services user
val myAuthenticatedUser = app.login(Credentials.anonymous())

// Define the configuration for the synced realm
val config =
    // Pass the authenticated user and the set of
    // all objects types you want to be able to sync
    SyncConfiguration.Builder(
        user = myAuthenticatedUser,
        schema = setOf(List::class, Item::class)
    )
        // Define an initial subscription with queries that include
        // the user's lists with incomplete items
        .initialSubscriptions{ realm ->
            add(realm.query<List>("ownerId == $0", myAuthenticatedUser.id),
                name = "user-lists"
            )
            add(realm.query<Item>("complete = false"),
                name = "incomplete-items"
            )
        }
        .build()

// Open the synced realm with the defined configuration
val realm = Realm.open(config)
Log.v("Successfully opened synced realm: ${realm.configuration.name}")
// Wait for initial subscriptions to sync to Atlas
realm.subscriptions.waitForSynchronization()

Realm の使用

構成された同期済み Realm が開かれたら、Realm 内のデータを操作できるようになります。 ローカル データを操作している間に、バックグラウンド スレッドが変更セットを効率的に統合、アップロード、ダウンロードします。

読み取り、書込み、変更の監視の構文は、同期されていない Realm の構文と同じです。 ただし、同期された Realm にデータを書き込む際には、追加の考慮事項があります。 詳細については、「 同期された Realm へのデータの書き込み - Kotlin SDK 」を参照してください。

サンプルアプリでは、新しい オブジェクトとList Itemオブジェクトを記述し、それらを同期された Realm にコピーします。

// Write List and Item objects to the synced realm
// Objects that match the subscription query are synced to Atlas
realm.write {
    val list = List().apply {
        name = "My Todo List"
        ownerId = myAuthenticatedUser.id
        items.add(Item().apply {
            name = "Check email"
            complete = false
        })
    }
    copyToRealm(list)
}
realm.syncSession.uploadAllLocalChanges(30.seconds)

オブジェクトはデバイスに正常に書込まれ、Atlas に同期されます。その理由は次のとおりです。

• どちらのオブジェクトもサブスクライブ クエリのパラメーター内にあります（ Listはユーザーが所有し、 Itemは不完全です）。

• 現在のユーザーにはバックエンドへのデータの書込み (write) 権限があります（ ロールにより、権限のあるユーザーはすべてのデータの読み取りと書込みを許可されます）。

書込み (write) 操作がクエリと一致しなかった場合、または現在のユーザーに必要な権限が ない 場合、Realm は 補完書込み (write) と呼ばれる致命的でないエラー操作で書込みを元に戻します。

次のステップ

アプリが必要なデータを Atlas に正常に同期すると、 Kotlin SDK で同期 の使用方法について詳しく知ることができます。

• 同期された Realm を設定して開きます - Kotlin SDK : デバッグ アプリ名の設定、カスタム リクエスト ヘッダーの提供、ディスパッチの指定など、利用可能なアプリ クライアント構成オプションについて学習します。

• 同期サブスクリプションの管理 - Kotlin SDK : アプリでサブスクライブ クエリを定義および管理する方法を学びます。

• 同期された Realm へのデータの書込み - Kotlin SDK : 同期された Realm への書込み方法、書込みエラーの修正の処理方法、パフォーマンスを向上させるために書込みをグループ化する方法について詳しく説明します。

• 同期セッションの管理 - Kotlin SDK : 同期セッションを通じて App Services との通信を管理する方法を学びます。

• 同期エラーの処理 - Kotlin SDK : クライアントのリセットなど、発生する可能性のある同期エラーを処理する方法を学びます。