Cómo usar los SDKs de iOS generados

Los SDKs cliente de Firebase Data Connect te permiten llamar a tus consultas y mutaciones del servidor directamente desde una app de Firebase. Generas un SDK cliente personalizado en paralelo a medida que diseñas los esquemas, las consultas y las mutaciones que implementas en tu servicio de Data Connect. Luego, integra los métodos de este SDK en la lógica de tu cliente.

Como ya mencionamos en otro lugar, es importante tener en cuenta que el código del cliente no envía las consultas ni las mutaciones, sino que se ejecutan en el servidor.Data Connect En cambio, cuando se implementan, las operaciones Data Connect se almacenan en el servidor, como Cloud Functions. Esto significa que debes implementar los cambios correspondientes del cliente para evitar que se interrumpa la experiencia de los usuarios existentes (por ejemplo, en versiones anteriores de la app).

Por eso, Data Connect te proporciona un entorno de desarrollo y herramientas que te permiten crear prototipos de tus esquemas, consultas y mutaciones implementados en el servidor. También genera automáticamente SDKs del cliente mientras creas prototipos.

Cuando hayas iterado las actualizaciones de tus apps de servicio y cliente, las actualizaciones del servidor y del cliente estarán listas para implementarse.

¿Cuál es el flujo de trabajo de desarrollo del cliente?

Si seguiste la sección Comienza ahora, se te presentó el flujo de desarrollo general de Data Connect. En esta guía, encontrarás información más detallada para generar SDKs de Swift a partir de tu esquema y trabajar con consultas y mutaciones del cliente.

Puedes aprender a desarrollar clientes con un repositorio de apps de inicio rápido y compilar una app de Data Connect con todas las funciones siguiendo nuestro codelab para iOS.

En resumen, para usar los SDKs de Swift generados en tus apps cliente, deberás seguir estos pasos previos:

1. Agrega Firebase a tu app para iOS.

2. Para usar el SDK generado, configúralo como una dependencia en Xcode.

   En la barra de navegación superior de Xcode, selecciona File > Add Package Dependencies > Add Local y elige la carpeta que contiene el Package.swift generado.

Luego, haz lo siguiente:

1. Desarrolla el esquema de tu app.

2. Configura la generación del SDK:

   • Con el botón Add SDK to app en nuestra extensión Data Connect de VS Code
   • Actualiza tu connector.yaml.

3. Inicializa tu código de cliente y bibliotecas de importación.

4. Implementa llamadas a consultas y mutaciones.

5. Configura y usa el emulador de Data Connect y realiza iteraciones.

Genera tu SDK de Swift

Al igual que con la mayoría de los proyectos de Firebase, el trabajo en el código del cliente de Firebase Data Connect se realiza en un directorio del proyecto local. Tanto la extensión Data Connect de VS Code como la CLI de Firebase son herramientas locales importantes para generar y administrar código de cliente.

Las opciones de generación del SDK se basan en varias entradas del archivo dataconnect.yaml que se generó cuando inicializaste tu proyecto.

Inicializa la generación del SDK

En tu connector.yaml, agrega tu outputDir, package y (para el SDK web) packageJsonDir.

connectorId: "movies"
generate:
  swiftSdk:
    outputDir: "../movies-generated"
    package: "Movies"

outputDir especifica dónde se debe generar el SDK. Si no se especifica, la carpeta del conector se usa como el directorio de salida predeterminado.

package especifica el nombre del paquete que se generará. El generador creará una carpeta con el nombre del paquete, que contendrá Package.swift y el código generado.

observablePublisher (opcional) especifica el publicador de Observable que se usará en las referencias de consultas. Los valores posibles son observableMacro (iOS 17 y versiones posteriores) y observableObject (iOS 16 y versiones anteriores). Si no se especifica ninguno, el valor predeterminado es observableMacro.

Nota: Puedes proporcionar una ruta de acceso absoluta al directorio de salida si tu proyecto está configurado en una estructura de directorios independiente.

Actualiza los SDKs mientras creas prototipos

Si prototipas de forma interactiva con la extensión Data Connect de VS Code y su emulador Data Connect, los archivos fuente del SDK se generan y actualizan automáticamente mientras modificas los archivos .gql que definen esquemas, consultas y mutaciones. Esta puede ser una función útil en los flujos de trabajo de recarga en caliente.

En otros casos, si usas el emulador Data Connect desde la CLI de Firebase, puedes establecer un monitoreo de las actualizaciones de .gql y también hacer que las fuentes del SDK se actualicen automáticamente.

Como alternativa, puedes usar la CLI para volver a generar los SDKs cada vez que se cambien los archivos .gql:

firebase dataconnect:sdk:generate --watch

Genera SDKs para la integración y para las versiones de producción

En algunos casos, como cuando preparas fuentes de proyectos para enviarlas a pruebas de CI, puedes llamar a la CLI de Firebase para realizar una actualización por lotes.

En estos casos, usa firebase dataconnect:sdk:generate.

Inicializa el SDK de iOS de Data Connect

Inicializa tu instancia de Data Connect con la información que usaste para configurar Data Connect (toda la información está disponible en la pestaña Data Connect de la consola de Firebase).

Cómo obtener una instancia de conector

El emulador de Data Connect generará el código de tu conector. Si el nombre del conector es movies y el paquete es movies, como se especifica en connector.yaml, recupera el objeto del conector llamando a lo siguiente:

let connector = DataConnect.moviesConnector

Implementa consultas y mutaciones

Con el objeto del conector, puedes ejecutar consultas y mutaciones según se definen en el código fuente de GraphQL. Supongamos que tu conector tiene definidas estas operaciones:

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

Luego, puedes crear una película de la siguiente manera:

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

Para recuperar una película, usarás una referencia de consulta. Todas las referencias de consulta son publicadores de Observable. Según el publicador configurado (consulta connector.yaml)), admiten la macro de @Observable (iOS 17 y versiones posteriores) o implementan el protocolo de ObservableObject. Si no se especifica ninguno, el valor predeterminado es la macro @Observable compatible con iOS 17 y versiones posteriores.

En una vista de SwiftUI, puedes vincular los resultados de la consulta con la variable data publicada de la referencia de la consulta y llamar al método execute() de la consulta para actualizar los datos. La variable data coincidirá con la forma de los datos que se definieron en la definición de la consulta de GQL.

Todos los resultados recuperados cumplen con el protocolo de Decodable. Si incluiste la clave principal del objeto en tu recuperación de GQL, los objetos también son Identifiable, lo que te permite usarlos en iteradores.

Nota: El objeto @StateObject no se actualiza en tiempo real. Tampoco es necesario cuando se usa una macro de @Observable como publicador.

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

Las consultas también admiten la ejecución única.

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

Crea un prototipo y prueba tu aplicación para iOS

Instrumenta clientes para usar un emulador local

Puedes usar el emulador de Data Connect, ya sea desde la extensión de Data Connect para VS Code o desde la CLI.

La instrumentación de la app para conectarse al emulador es la misma en ambos casos.

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

Tipos de datos en los SDK de Data Connect

El servidor Data Connect representa tipos de datos GraphQL comunes y personalizados. En el SDK, se representan de la siguiente manera.

Tipo de conexión de datos	Swift
String	String
Int	Int
Número de punto flotante	Doble
Booleano	Bool
UUID	UUID
Fecha	FirebaseDataConnect.LocalDate
Marca de tiempo	FirebaseCore.Timestamp
Int64	Int64
Cualquiera	FirebaseDataConnect.AnyValue