Usar SDKs do iOS gerados

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

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

Por isso, o Data Connect oferece um ambiente de desenvolvimento 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 enquanto você cria o protótipo.

Depois de iterar as atualizações nos apps de serviço e cliente, as atualizações do lado do servidor e do cliente estão prontas para implantação.

Gerar o SDK para Swift

Como na maioria dos projetos do Firebase, o trabalho no código do cliente Firebase Data Connect acontece em um diretório de projeto local. A extensão do Data Connect para VS Code e a CLI Firebase são ferramentas locais importantes para gerar e gerenciar o código do cliente.

As opções de geração do SDK são vinculadas a várias entradas no arquivo dataconnect.yaml gerado quando você inicializou o projeto.

Inicializar a geração do SDK

No connector.yaml, adicione outputDir, package e (para o SDK da Web) packageJsonDir. 
connectorId: "movies"
generate:
  swiftSdk:
    outputDir: "../movies-generated"
    package: "Movies"

outputDir especifica para onde o SDK gerado precisa ser enviado. Se não for especificado, a pasta do conector será usada como o diretório de saída padrão.

package especifica o nome do pacote que será gerado. O gerador vai criar uma pasta com o nome do pacote, contendo Package.swift e o código gerado.

observablePublisher (opcional) especifica o editor do Observable a ser usado nas referências de consulta. Os valores possíveis são observableMacro (iOS 17+) e observableObject (antes do iOS 17). O valor padrão, se nenhum for especificado, é observableMacro.

Atualizar SDKs durante a prototipagem

Se você estiver criando protótipos de forma interativa com a extensão do Data Connect para o VS Code e o emulador Data Connect, os arquivos de origem do SDK serão gerados e atualizados automaticamente enquanto você modifica arquivos .gql que definem esquemas, consultas e mutações. Esse pode ser um recurso útil em fluxos de trabalho de (re)carregamento em tempo real.

Em outros cenários, se você estiver usando o emulador Data Connect da CLI Firebase, poderá definir um monitoramento nas atualizações .gql e também ter as origens do SDK atualizadas automaticamente.

Como alternativa, use a CLI para regenerar SDKs sempre que os arquivos .gql forem alterados:

firebase dataconnect:sdk:generate --watch

Gerar SDKs para integração e lançamentos de produção

Em alguns casos, como ao preparar fontes de projeto para envio para testes de CI, é possível chamar a CLI Firebase para uma atualização em lote.

Nesses casos, use firebase dataconnect:sdk:generate.

Configurar o código do cliente

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

Em seguida, abra o espaço de trabalho do app usando o Xcode.

Na barra de navegação de cima, selecione File > Add Package Dependencies > Add Local e escolha a pasta que contém o arquivo de origem Package.swift gerado.

Inicializar o SDK do Data Connect para iOS

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

Como acessar uma instância do conector

O código do conector será gerado pelo emulador Data Connect. Se o nome do conector for movies e o pacote for movies, conforme especificado em connector.yaml, extraia o objeto do conector chamando:

let connector = DataConnect.moviesConnector

Como executar consultas e mutações

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, crie um filme da seguinte maneira:

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 um filme, use uma referência de consulta. Todas as referências de consulta são editores observáveis. Dependendo do editor configurado (consulte connector.yaml)), ele pode oferecer suporte à macro @Observable (iOS 17+) ou implementar o protocolo ObservableObject. O padrão, se nenhum for especificado, é a macro @Observable com suporte no iOS 17 ou mais recente.

Em uma visualização SwiftUI, é possível vincular os resultados da consulta usando a variável data publicada da referência de consulta e chamar o método execute() da consulta para atualizar os dados. A variável data vai corresponder à forma dos dados definidos na definição da consulta GQL.

Todos os resultados recuperados obedecem ao protocolo Decodable. Se você incluiu a chave primária do objeto na busca do GQL, os objetos também são Identifiable, permitindo que você os use em iteradores. 

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

As consultas também oferecem suporte à execução única. 

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

Criar protótipos e testar seu aplicativo iOS

Instrumentar clientes para usar um emulador local

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

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

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 dados nos SDKs do Data Connect

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

Tipo de conexão de dados Swift
String String
Int Int
Ponto flutuante Duplo
Booleano Booleano
UUID UUID
Data FirebaseDataConnect.LocalDate
Carimbo de data/hora FirebaseCore.Timestamp
Int64 Int64
Qualquer FirebaseDataConnect.AnyValue