Adicionar Device Sync a um aplicativo - Kotlin SDK

Device Sync

O Device Sync sincroniza dados entre dispositivos cliente e o Atlas. Os dados são mantidos em um dispositivo, mesmo quando estiver off-line. Quando o dispositivo tem uma conexão de rede, o Device Sync carrega e baixa dados em background e gerencia a resolução de conflitos.

Os dados sincronizados entre seu aplicativo cliente e o Atlas são determinados pelas permissões de um usuário para acessar dados qualificados. Os dados elegíveis são a interseção de:

• Modelo de dados: suas informações de tipo de dados

• Queries de assinatura: as condições que definem quais dados armazenar

• Permissões: as permissões baseadas em funções necessárias para interagir com dados que atendam às condições especificadas

Para obter uma explicação detalhada do Device Sync, consulte Introdução ao Atlas Device Sync na documentação do Atlas App Services .

Pré-requisitos

Você pode adicionar o Device Sync a um aplicativo de várias maneiras, dependendo do estado do aplicativo e dos seus dados. Este guia descreve como adicionar a sincronização a um aplicativo cliente existente usando o Modo de desenvolvimento. Este guia pressupõe que seu aplicativo use o Realm Kotlin SDK e que você já definiu um modelo de dados no código do cliente.

Como o Device Sync conecta seu aplicativo cliente ao backend do Atlas App Services por meio de um Atlas App Services , você precisa seguir antes de começar:

1. Um aplicativo Atlas App Services com autenticação ativada. Para saber como, consulte Criar um App Services App do App Services na documentação do Atlas App Services .

2. Confirme que seu aplicativo pode se conectar ao back-end do Atlas App Services . Para saber como, consulte Conectar-se ao Atlas App Services - Kotlin SDK.

Sobre os exemplos nesta página

Os exemplos nesta página referem-se a um exemplo do aplicativo Kotlin Todo com um Modelo de dados Realm já definido que inclui um objeto List contendo uma lista de objetos Item :

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
}

Habilitar o Device Sync nos App Services

Você deve primeiro ativar o Device Sync em seu aplicativo Atlas App Services antes de adicionar a sincronização ao seu aplicativo cliente.

Para habilitar o Device Sync em seu aplicativo, conclua as etapas descritas no procedimento Configurar e habilitar o Atlas Device Sync na documentação do Atlas App Services .

Durante esse processo, você pode escolher se deseja ativar o Modo de desenvolvimento e pode selecionar uma função padrão para os usuários do seu aplicativo. Para obter mais informações sobre as configurações disponíveis, consulte Configurações de sincronização na documentação do App Services.

Para nosso aplicativo de exemplo , ativamos a Device Sync com o modo de desenvolvimento e, em seguida, adicionamos a função padrão "O usuário pode ler e escrever todos os dados". Isso significa que, para um usuário autorizado com uma conexão de rede, o Device Sync baixa os dados qualificados para o cliente e o Atlas permite as gravações no cliente e, em seguida, sincroniza-as com o backend. Para saber mais sobre o que acontece quando um usuário autorizado não tem uma conexão de rede, consulte Compensating Writes.

Adicionar sincronização ao seu aplicativo cliente

Depois de configurar e habilitar a sincronização no Atlas App Services, você poderá adicionar a sincronização à sua aplicação cliente.

// 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()

Use o Realm

Agora que você abriu o Realm sincronizado configurado, pode trabalhar com seus dados no Realm. Enquanto você trabalha com dados locais, um thread em segundo plano integra, carrega e baixa conjuntos de alterações de forma eficiente.

A sintaxe para ler, escrever e observar alterações é idêntica à sintaxe para domínios não sincronizados. No entanto, há considerações adicionais ao escrever dados em um Realm sincronizado. Para obter mais informações, consulte Gravar dados em um domínio sincronizado - Realm Kotlin SDK.

Para nosso aplicativo de exemplo , escrevemos um novo objeto List e Item e, em seguida, os copiamos para o Realm sincronizado:

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

Os objetos gravam com sucesso no dispositivo e, em seguida, sincronizam com o Atlas porque:

• Ambos os objetos estão dentro dos parâmetros da consulta de assinatura (o List é de propriedade do usuário e o Item está incompleto).

• O usuário atual tem permissão para gravar dados no backend (a função permite que usuários autorizados leiam e escrevam todos os dados).

Se nossa operação de gravação não corresponder à query ou o usuário atual não tiver as permissões necessárias, o Realm reverterá a gravação com uma operação de erro não fatal chamada gravação compensatória.

Próximos passos

Depois que seu aplicativo estiver sincronizando com sucesso os dados desejados com o Atlas, você poderá saber mais sobre como usar a sincronização com o Kotlin SDK:

• Configurar e abrir um domínio sincronizado - Realm Kotlin SDK: saiba mais sobre as opções de configuração do cliente de aplicativo disponíveis, como definir um nome de aplicativo de depuração, fornecer cabeçalhos de solicitação personalizados ou especificar um despachante.

• Gerenciar assinaturas de sincronização - Kotlin SDK: saiba como definir e gerenciar as queries de assinatura em seu aplicativo.

• Gravar dados em um domínio sincronizado - Realm Kotlin SDK: saiba mais sobre como escrever em um Realm sincronizado , como lidar com erros de gravação compensatórios e como agrupar gravações para melhorar o desempenho.

• Gerenciar uma sessão de sincronização - Kotlin SDK: saiba como gerenciar a comunicação com o App Services por meio de sessões de sincronização.

• Lidar com erros de sincronização - Kotlin SDK: saiba como lidar com erros de sincronização que podem ocorrer, incluindo redefinições do cliente.