Usa gli SDK Android generati

Firebase Data Connect SDK client ti consentono di chiamare le query e le mutazioni lato server direttamente da un'app Firebase. Generi un SDK client personalizzato in parallelo alla progettazione degli schemi, delle query e delle mutazioni di cui esegui il deployment nel tuo Data Connect servizio. Poi, integri i metodi di questo SDK nella logica client.

Come abbiamo già detto, è importante notare che Data Connect query e mutazioni non vengono inviate dal codice client ed eseguite sul server. Quando viene eseguito il deployment, le operazioni Data Connect vengono archiviate su il server come Cloud Functions. Ciò significa che devi eseguire il deployment delle modifiche lato client corrispondenti per evitare di interrompere gli utenti esistenti (ad esempio, nelle versioni precedenti dell'app).

Per questo motivo, Data Connect ti fornisce un ambiente di sviluppo e strumenti che ti consentono di creare prototipi di schemi, query e mutazioni di cui è stato eseguito il deployment sul server. Genera anche automaticamente gli SDK lato client durante la creazione del prototipo.

Dopo aver eseguito l'iterazione degli aggiornamenti delle app client e del servizio, gli aggiornamenti lato server e lato client sono pronti per il deployment.

Che cos'è il flusso di lavoro di sviluppo client?

Se hai seguito la guida Introduzione, hai scoperto il flusso di sviluppo generale per Data Connect. In questa guida troverai informazioni più dettagliate sulla generazione di SDK Android dallo schema e sull'utilizzo di query e mutazioni client.

Puoi imparare lo sviluppo client con un repository di app di avvio rapido e creare un'app completa Data Connect seguendo il nostro codelab per Android.

Per riassumere, per utilizzare gli SDK Android generati nelle app client, segui questi passaggi preliminari:

1. Aggiungi Firebase alla tua app Android.
2. Configura Data Connect come dipendenza in Gradle.
3. Aggiungi il plug-in Gradle di serializzazione Kotlin e la dipendenza Gradle.

Quindi:

1. Sviluppa lo schema dell'app.

2. Configura la generazione dell'SDK:

   • Con il pulsante Aggiungi SDK all'app nella nostra estensione Data Connect VS Code
   • Aggiornando il tuo connector.yaml

3. Inizializza il codice client e importa le librerie.

4. Implementa le chiamate a query e mutazioni.

5. Configura e utilizza l'emulatore Data Connect ed esegui l'iterazione.

Genera l'SDK Kotlin

Utilizza l'interfaccia a riga di comando Firebase per configurare gli SDK generati da Data Connect nelle tue app. Il comando init dovrebbe rilevare tutte le app nella cartella corrente e installare automaticamente gli SDK generati.

firebase init dataconnect:sdk

Aggiorna gli SDK durante la creazione del prototipo

Se hai installato l'estensione Data Connect VS Code, gli SDK generati saranno sempre aggiornati.

Se non utilizzi l'estensione Data Connect VS Code, puoi utilizzare l'interfaccia a riga di comando di Firebase per mantenere aggiornati gli SDK generati.

firebase dataconnect:sdk:generate --watch

Genera SDK nelle pipeline di build

Puoi utilizzare l'interfaccia a riga di comando di Firebase per generare gli SDK Data Connect nei processi di build CI/CD.

firebase dataconnect:sdk:generate

Configura il codice client

Incorpora Data Connect nel codice client

Per configurare il codice client in modo da utilizzare Data Connect e l'SDK generato, segui innanzitutto le istruzioni di configurazione standard di Firebase.

Poi, aggiungi quanto segue alla sezione plugins in 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

Poi, aggiungi quanto segue alla sezione dependencies in 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

Inizializza l'SDK Android Data Connect

Inizializza l'istanza Data Connect utilizzando le informazioni che hai utilizzato per configurare Data Connect (tutte disponibili nella scheda Data Connect della console Firebase).

L'oggetto ConnectorConfig

L'SDK richiede un oggetto di configurazione del connettore.

Questo oggetto viene generato automaticamente da serviceId e location in dataconnect.yaml e connectorId in connector.yaml.

Recupera un'istanza del connettore

Ora che hai configurato un oggetto di configurazione, recupera un'istanza del Data Connect connettore. Il codice del connettore verrà generato dall' Data Connect emulatore. Se il nome del connettore è movies e il pacchetto Kotlin è com.myapplication, come specificato in connector.yaml, recupera l'oggetto del connettore chiamando:

val connector = com.myapplication.MoviesConnector.instance

Utilizza query e mutazioni dall'SDK Android

Con l'oggetto del connettore, puoi eseguire query e mutazioni come definito nel codice sorgente GraphQL. Supponiamo che il connettore abbia queste operazioni definite:

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

Poi, potresti creare e recuperare un film nel seguente modo:

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

Puoi anche recuperare più film:

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)

Puoi anche raccogliere un Flow che produrrà un risultato solo quando viene recuperato un nuovo risultato della query utilizzando una chiamata al metodo execute() della query.

Nota: questo flusso non viene aggiornato in tempo reale.

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

Gestisci le modifiche ai campi di enumerazione

Lo schema di un'app può contenere enumerazioni, a cui è possibile accedere tramite le query GraphQL.

Man mano che il design di un'app cambia, potresti aggiungere nuovi valori supportati per l'enumerazione. Ad esempio, supponiamo che in un secondo momento nel ciclo di vita dell'applicazione tu decida di aggiungere un valore FULLSCREEN all'enumerazione AspectRatio.

Nel flusso di lavoro Data Connect, puoi utilizzare gli strumenti di sviluppo locali per aggiornare le query e gli SDK.

Tuttavia, prima di rilasciare una versione aggiornata dei client, i client di cui è stato eseguito il deployment precedente potrebbero non funzionare.

Esempio di implementazione resiliente

L'SDK generato impone la gestione dei valori sconosciuti, poiché il codice del cliente deve decomprimere l'oggetto EnumValue, che è EnumValue.Known per i valori di enumerazione noti o EnumValue.Unknown per i valori sconosciuti.

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

Crea prototipi e testa l'app per Android

Strumenta i client per utilizzare un emulatore locale

Puoi utilizzare l'emulatore Data Connect, sia dall' estensione Data Connect VS Code sia dall'interfaccia a riga di comando.

La strumentazione dell'app per la connessione all'emulatore è la stessa in entrambi gli scenari.

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

Per passare alle risorse di produzione, commenta le righe per la connessione all'emulatore.

Tipi di dati negli SDK Data Connect

Il server Data Connect rappresenta i tipi di dati GraphQL comuni e personalizzati. Questi sono rappresentati nell'SDK come segue.

Data Connect Tipo	Kotlin
Stringa	Stringa
Int	Int (intero a 32 bit)
In virgola mobile	Double (virgola mobile a 64 bit)
Booleano	Booleano
UUID	java.util.UUID
Data	com.google.firebase.dataconnect.LocalDate (era java.util.Date fino alla versione 16.0.0-beta03)
Timestamp	com.google.firebase.Timestamp
Int64	Lungo
Qualsiasi	com.google.firebase.dataconnect.AnyValue