Utilizzare gli SDK per iOS generati

Gli SDK client Firebase Data Connect 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 che implementi nel tuo servizio Data Connect. Poi, integra i metodi di questo SDK nella logica del client.

Come abbiamo già detto, è importante notare che Data Connect le query e le mutazioni non vengono inviate dal codice client ed eseguite sul server. Al contrario, quando viene eseguito il deployment, le operazioni Data Connect vengono archiviate sul server come Cloud Functions. Ciò significa che devi implementare le modifiche lato client corrispondenti per evitare di interrompere l'esperienza degli 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 implementati sul server. Inoltre, genera automaticamente gli SDK lato client durante la prototipazione.

Una volta completate le iterazioni degli aggiornamenti del servizio e delle app client, gli aggiornamenti lato server e lato client sono pronti per il deployment.

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

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

Puoi imparare a sviluppare client con un repository di app di avvio rapido e creare un'app Data Connect completa seguendo il nostro codelab per iOS.

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

1. Aggiungi Firebase alla tua app iOS.

2. Per utilizzare l'SDK generato, configuralo come dipendenza in Xcode.

   Nella barra di navigazione superiore di Xcode, seleziona File > Add Package Dependencies > Add Local (File > Aggiungi dipendenze pacchetto > Aggiungi locale) e scegli la cartella contenente il file Package.swift generato.

Quindi:

1. Sviluppa lo schema dell'app.

2. Configura la generazione dell'SDK:

   • Con il pulsante Aggiungi SDK all'app nella nostra estensione VS Code Data Connect
   • 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'Data Connect emulatore e itera.

Genera l'SDK Swift

Utilizza la CLI Firebase per configurare gli SDK generati da Data Connect nelle tue app. Il comando init deve rilevare tutte le app nella cartella corrente e installare automaticamente gli SDK generati.

firebase init dataconnect:sdk

Aggiornare gli SDK durante la prototipazione

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

Se non utilizzi l'estensione VS Code di Data Connect, 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 SDK Data Connect nei processi di build CI/CD.

firebase dataconnect:sdk:generate

Inizializza l'SDK Data Connect per iOS

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

Recupero di un'istanza del connettore

Il codice per il connettore verrà generato dall'emulatore Data Connect. Se il nome del connettore è movies e il pacchetto è movies, come specificato in connector.yaml, recupera l'oggetto connettore chiamando:

let connector = DataConnect.moviesConnector

Implementare query e mutazioni

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

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

A questo punto puoi creare un filmato nel seguente modo:

let mutationResult = try await connector.createMovieMutation.execute(
  title: "Empire Strikes Back",
  releaseYear: 1980,
  genre: "Sci-Fi",
  rating: 5)

print("Movie ID: \(mutationResult.data.movie_insert.id)")

Per recuperare un film, utilizzerai un riferimento alla query. Tutti i riferimenti alle query sono publisher osservabili. A seconda del publisher configurato (vedi connector.yaml)), supportano la macro @Observable (iOS 17+) o implementano il protocollo ObservableObject. Se non viene specificato alcun valore, il valore predefinito è la macro @Observable supportata su iOS 17 e versioni successive.

In una visualizzazione SwiftUI, puoi associare i risultati della query utilizzando la variabile data pubblicata del riferimento alla query e chiamare il metodo execute() della query per aggiornare i dati. La variabile data corrisponderà alla forma dei dati definita nella definizione della query GQL.

Tutti i risultati recuperati sono conformi al protocollo Decodable. Se hai incluso la chiave primaria dell'oggetto nel recupero GQL, gli oggetti sono anche Identifiable, il che ti consente di utilizzarli negli iteratori.

Nota :il @StateObject non viene aggiornato in tempo reale. Inoltre, non è necessario quando si utilizza una macro @Observable come publisher.

struct ListMovieView: View {
    @StateObject private var queryRef = connector.listMoviesByGenreQuery.ref(genre: "Sci-Fi")
    var body: some View {
        VStack {
            Button {
                Task {
                    do {
                        try await refresh()
                    } catch {
                        print("Failed to refresh: \(error)")
                    }
                }
            } label: {
                Text("Refresh")
            }
                // use the query results in a view
            ForEach(queryRef.data?.movies ?? [], id: \.self.id) { movie in
                    Text(movie.title)
                }
            }
    }
    @MainActor
    func refresh() async throws {
        _ = try await queryRef.execute()
    }
}

Le query supportano anche l'esecuzione una tantum.

let resultData = try await DataConnect.moviesConnector.listMoviesByGenreQuery.execute(genre: "Sci-Fi")

Gestire 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, puoi aggiungere nuovi valori enum supportati. Ad esempio, immagina di decidere di aggiungere un valore FULLSCREEN all'enumerazione AspectRatio in un secondo momento del ciclo di vita della tua applicazione.

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 meno recenti potrebbero non funzionare.

Esempio di implementazione resiliente

L'SDK generato impone la gestione dei valori sconosciuti poiché gli enum generati contengono un valore _UNKNOWN e Swift applica istruzioni switch esaustive.

do {
    let result = try await DataConnect.moviesConnector.listMovies.execute()
    if let data = result.data {
        for movie in data.movies {
            switch movie.aspectratio {
                case .ACADEMY: print("academy")
                case .WIDESCREEN: print("widescreen")
                case .ANAMORPHIC: print("anamorphic")
                case ._UNKNOWN(let unknownAspect): print(unknownAspect)
            }
        }
    }
} catch {
    // handle error
}

Abilita la memorizzazione nella cache lato client

Data Connect ha una funzionalità di memorizzazione nella cache lato client facoltativa, che puoi attivare modificando il file connector.yaml. Quando questa funzionalità è abilitata, gli SDK client generati memorizzano nella cache locale le risposte alle query, il che può ridurre il numero di richieste al database effettuate dalla tua app e consente alle parti dell'app che dipendono dal database di funzionare quando la disponibilità di rete è interrotta.

Per attivare la memorizzazione nella cache lato client, aggiungi una configurazione della memorizzazione nella cache lato client alla configurazione del connettore:

generate:
  swiftSdk:
    outputDir: "../ios"
    package: "FirebaseDataConnectGenerated"
    clientCache:
      maxAge: 5s
      storage: persistent

Questa configurazione ha due parametri, entrambi facoltativi:

• maxAge: l'età massima di una risposta memorizzata nella cache prima che l'SDK client recuperi valori aggiornati. Esempi: "0", "30s", "1h30m".

  Il valore predefinito per maxAge è 0, il che significa che le risposte vengono memorizzate nella cache, ma l'SDK client recupererà sempre valori aggiornati. I valori memorizzati nella cache verranno utilizzati solo quando CACHE_ONLY è impostato su execute().

• storage: l'SDK client può essere configurato per memorizzare nella cache le risposte nello spazio di archiviazione persistent o in memory. I risultati memorizzati nella cache nello spazio di archiviazione persistent rimarranno disponibili anche dopo il riavvio dell'app. Negli SDK per iOS, il valore predefinito è persistent.

Dopo aver aggiornato la configurazione della memorizzazione nella cache del connettore, rigenera gli SDK client e ricompila l'app. Una volta fatto, execute() memorizzerà nella cache le risposte e utilizzerà i valori memorizzati nella cache in base alle norme che hai configurato. In genere questo avviene automaticamente, senza ulteriori interventi da parte tua; tuttavia, tieni presente quanto segue:

• Il comportamento predefinito di execute() è quello descritto sopra: se un risultato viene memorizzato nella cache per una query e il valore memorizzato nella cache non è precedente a maxAge, utilizza il valore memorizzato nella cache. Questo comportamento predefinito è chiamato criterio PREFER_CACHE.

  Puoi anche specificare le singole chiamate di execute() per servire solo i valori memorizzati nella cache (CACHE_ONLY) o per recuperare in modo incondizionato i valori aggiornati dal server (SERVER_ONLY).

  try await execute(fetchPolicy: .cacheOnly)
  

  try await execute(fetchPolicy: .serverOnly)
  

  Prototipa e testa l'applicazione per iOS

  Strumentare i client per utilizzare un emulatore locale

  Puoi utilizzare l'emulatore Data Connect, sia dall'estensione VS Code Data Connect sia dalla CLI.

  L'instrumentazione dell'app per la connessione all'emulatore è la stessa per entrambi gli scenari.

  let connector = DataConnect.moviesConnector
  // Connect to the emulator on "127.0.0.1:9399"
  connector.useEmulator()
  
  // (alternatively) if you're running your emulator on non-default port:
  connector.useEmulator(port: 9999)
  
  // Make calls from your app
  

  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.

  Tipo di Data Connect	Swift
  Stringa	Stringa
  Int	Int
  In virgola mobile	Doppio
  Booleano	Bool
  UUID	UUID
  Data	FirebaseDataConnect.LocalDate
  Timestamp	FirebaseCore.Timestamp
  Int64	Int64
  Qualsiasi	FirebaseDataConnect.AnyValue