Usar SDKs do Android gerados

Os SDKs de cliente Firebase Data Connect permitem chamar consultas e mutações do lado do servidor diretamente de um app do Firebase. Você gera um SDK de cliente personalizado em paralelo ao projetar os esquemas, consultas e mutações que implanta no seu serviço Data Connect. Em seguida, integre métodos desse SDK à lógica do cliente.

Como já mencionamos, é importante observar que as Data Connect consultas e mutações não são enviadas pelo código do cliente e executadas no servidor. Em vez disso, quando implantadas, as Data Connect operações são armazenadas no servidor, como as Cloud Functions. Isso significa que você precisa implantar as mudanças correspondentes do lado do cliente para evitar que os usuários atuais (por exemplo, em versões mais antigas do app) sejam afetados.

É por isso que Data Connect oferece um ambiente de desenvolvedor e ferramentas que permitem criar protótipos de esquemas, consultas e mutações implantados no servidor. Ele também gera SDKs do lado do cliente automaticamente durante a criação do protótipo.

Quando você itera atualizações nos apps de serviço e cliente, as atualizações do servidor e do lado do cliente ficam prontas para implantação.

Qual é o fluxo de trabalho de desenvolvimento do cliente?

Se você seguiu o guia de introdução, já conhece o fluxo de desenvolvimento geral do Data Connect. Neste guia, você encontra informações mais detalhadas sobre como gerar SDKs do Android com base no esquema e trabalhar com consultas e mutações do cliente.

Para resumir, para usar os SDKs do Android gerados nos apps de cliente, siga estas etapas de pré-requisito:

1. Adicione o Firebase ao seu Android app.
2. Configure Data Connect como uma dependência no Gradle.
3. Adicione o plug-in de serialização do Kotlin e a dependência do Gradle.

Em seguida:

1. Desenvolva o esquema do app.

2. Configure a geração do SDK:

   • Com o botão Adicionar SDK ao app na extensão do Data Connect para VS Code
   • Ao atualizar seu connector.yaml

3. Inicialize o código do cliente e importe bibliotecas.

4. Implemente chamadas para consultas e mutações.

5. Configure e use o emulador Data Connect e faça iterações.

Gerar o SDK do Kotlin

Use a Firebase CLI para configurar os Data Connect gerados nos seus apps. O comando init detecta todos os apps na pasta atual e instala os SDKs gerados automaticamente.

firebase init dataconnect:sdk

Atualizar SDKs durante a criação de protótipos

Se você tiver a extensão do Data Connect para VS Code instalada, ela sempre manterá os SDKs gerados atualizados.

Se você não usa a extensão do Data Connect para VS Code, use a CLI do Firebase para manter os SDKs gerados atualizados.

firebase dataconnect:sdk:generate --watch

Gerar SDKs em pipelines de build

Você pode usar a CLI do Firebase para gerar Data Connect SDKs em processos de build de CI/CD.

firebase dataconnect:sdk:generate

Configurar o código do cliente

Incorporar Data Connect ao código do cliente

Para configurar o código do cliente para usar Data Connect e o SDK gerado, primeiro siga as instruções de configuração padrão do Firebase.

Em seguida, adicione o seguinte à seção plugins em app/build.gradle.kts:

// The Firebase team tests with version 1.8.22; however, other 1.8 versions,
// and all newer versions are expected work too.
kotlin("plugin.serialization") version "1.8.22" // MUST match the version of the Kotlin compiler

Em seguida, adicione o seguinte à seção dependencies em app/build.gradle.kts:

implementation(platform("com.google.firebase:firebase-bom:34.11.0"))
implementation("com.google.firebase:firebase-dataconnect")
implementation("com.google.firebase:firebase-auth") // Optional
implementation("com.google.firebase:firebase-appcheck") // Optional
implementation("org.jetbrains.kotlinx:kotlinx-coroutines-core:1.7.3") // Newer versions should work too
implementation("org.jetbrains.kotlinx:kotlinx-serialization-core:1.5.1") // Newer versions should work too

Inicializar o SDK do Android Data Connect

Inicialize a instância do Data Connect usando as informações que você usou para configurar o Data Connect (tudo disponível na guia "Data Connect" do console do Firebase).

O objeto ConnectorConfig

O SDK exige um objeto de configuração do conector.

Esse objeto é gerado automaticamente de serviceId e location em dataconnect.yaml e connectorId em connector.yaml.

Como receber uma instância do conector

Agora que você configurou um objeto de configuração, receba uma instância do Data Connect conector. O código do conector será gerado pelo Data Connect emulador. Se o nome do conector for movies e o pacote do Kotlin for com.myapplication, conforme especificado em connector.yaml, recupere o objeto do conector chamando:

val connector = com.myapplication.MoviesConnector.instance

Usar consultas e mutações do SDK do Android

Com o objeto do conector, é possível executar consultas e mutações conforme definido no código-fonte do GraphQL. Suponha que o conector tenha estas operações definidas:

mutation createMovie($title: String!, $releaseYear: Int!, $genre: String!, $rating: Int!) {
  movie_insert(data: {
    title: $title
    releaseYear: $releaseYear
    genre: $genre
    rating: $rating
  })
}

query getMovieByKey($key: Movie_Key!) {
  movie(key: $key) { id title }
}

query listMoviesByGenre($genre: String!) {
  movies(where: {genre: {eq: $genre}}) {
    id
    title
  }
}

Em seguida, você pode criar e recuperar um filme da seguinte maneira:

val connector = MoviesConnector.instance

val addMovieResult1 = connector.createMovie.execute(
  title = "Empire Strikes Back",
  releaseYear = 1980,
  genre = "Sci-Fi",
  rating = 5
)

val movie1 = connector.getMovieByKey.execute(addMovieResult1.data.key)

println("Empire Strikes Back: ${movie1.data.movie}")

Também é possível recuperar vários filmes:

val connector = MoviesConnector.instance

val addMovieResult2 = connector.createMovie.execute(
  title="Attack of the Clones",
  releaseYear = 2002,
  genre = "Sci-Fi",
  rating = 5
)

val listMoviesResult = connector.listMoviesByGenre.execute(genre = "Sci-Fi")

println(listMoviesResult.data.movies)

Também é possível coletar um Flow que só produzirá um resultado quando um novo resultado de consulta for recuperado usando uma chamada para o método execute() da consulta.

val connector = MoviesConnector.instance

connector.listMoviesByGenre.flow(genre = "Sci-Fi").collect { data ->
  println(data.movies)
}

connector.createMovie.execute(
  title="A New Hope",
  releaseYear = 1977,
  genre = "Sci-Fi",
  rating = 5
)

connector.listMoviesByGenre.execute(genre = "Sci-Fi") // will cause the Flow to get notified

Processar mudanças nos campos de enumeração

O esquema de um app pode conter enumerações, que podem ser acessadas pelas suas consultas do GraphQL.

À medida que o design de um app muda, você pode adicionar novos valores compatíveis com enumeração. Por exemplo, imagine que, mais tarde no ciclo de vida do aplicativo, você decida adicionar um valor FULLSCREEN à enumeração AspectRatio.

No fluxo de trabalho Data Connect, é possível usar ferramentas de desenvolvimento local para atualizar consultas e SDKs.

No entanto, antes de lançar uma versão atualizada dos clientes, os clientes implantados mais antigos podem ser interrompidos.

Exemplo de implementação resiliente

O SDK gerado força o processamento de valores desconhecidos, já que o código do cliente precisa desembrulhar o EnumValue objeto, que é EnumValue.Known para valores de enumeração conhecidos ou EnumValue.Unknown para valores desconhecidos.

val result = connector.listMoviesByAspectRatio.execute(AspectRatio.WIDESCREEN)
val encounteredAspectRatios = mutableSetOf<String>()

result.data.movies
  .mapNotNull { it.otherAspectRatios }
  .forEach { otherAspectRatios ->
    otherAspectRatios
      .filterNot { it.value == AspectRatio.WIDESCREEN }
      .forEach {
        when (it) {
          is EnumValue.Known -> encounteredAspectRatios.add(it.value.name)
          is EnumValue.Unknown ->
            encounteredAspectRatios.add("[unknown ratio: ${it.stringValue}]")
        }
      }
  }

println(
  "Widescreen movies also include additional aspect ratios: " +
    encounteredAspectRatios.sorted().joinToString()
)

Criar protótipos e testar o app Android

Instrumentar clientes para usar um emulador local

É possível usar o Data Connect emulador, seja na extensão do Data Connect para VS Code ou na CLI.

A instrumentação do app para se conectar ao emulador é a mesma para os dois cenários.

val connector = MoviesConnector.instance

// Connect to the emulator on "10.0.2.2:9399"
connector.dataConnect.useEmulator()

// (alternatively) if you're running your emulator on non-default port:
connector.dataConnect.useEmulator(port = 9999)

// Make calls from your app

Para mudar para recursos de produção, comente as linhas de conexão com o emulador.

Tipos de dados nos Data Connect SDKs

O servidor Data Connect representa tipos de dados comuns e personalizados do GraphQL. Eles são representados no SDK da seguinte maneira.