Usar SDKs do iOS gerados

Com os SDKs do cliente do Firebase Data Connect, é possível 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, as consultas e as mutações que implanta no seu serviço Data Connect. Em seguida, integre métodos desse SDK à lógica do cliente.

Como mencionamos em outro lugar, é importante observar que as consultas e mutações não são enviadas pelo código do cliente e executadas no servidor.Data Connect 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 falhas nos usuários atuais (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 protótipos.

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

Qual é o fluxo de trabalho de desenvolvimento do cliente?

Se você seguiu os Primeiros passos, conheceu o fluxo geral de desenvolvimento do Data Connect. Neste guia, você encontra informações mais detalhadas sobre como gerar SDKs Swift do seu esquema e trabalhar com consultas e mutações do cliente.

Em resumo, para usar os SDKs Swift gerados nos seus apps cliente, siga estas etapas de pré-requisito:

1. Adicione o Firebase ao seu app iOS.

2. Para usar o SDK gerado, configure-o como uma dependência no Xcode.

   Na barra de navegação superior do Xcode, selecione Arquivo > Adicionar dependências de pacote > Adicionar local e escolha a pasta que contém o Package.swift gerado.

Depois, siga estas instruções:

1. Desenvolva o esquema do app.

2. Configure a geração de SDKs:

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

3. Inicialize o código do cliente e importe as 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 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 VS Code e a CLI Firebase são ferramentas locais importantes para gerar e gerenciar código do cliente.

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

Inicializar a geração de SDK

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

outputDir especifica onde o SDK gerado deve ser exibido. 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 de Observable a ser usado em referências de consulta. Os valores possíveis são observableMacro (iOS 17 ou mais recente) e observableObject (versões anteriores ao iOS 17). O valor padrão, se nenhum for especificado, é observableMacro.

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

Se você estiver criando protótipos interativamente com a extensão Data Connect do VS Code e o emulador Data Connect, os arquivos de origem do SDK serão gerados e atualizados automaticamente enquanto você modifica os arquivos .gql que definem esquemas, consultas e mutações. Esse pode ser um recurso útil em fluxos de trabalho de recarga (automática) dinâmica.

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

firebase dataconnect:sdk:generate --watch

Gerar SDKs para integração e para versões de produção

Em alguns casos, como ao preparar fontes de projetos para enviar para testes de CI, você pode chamar a CLI Firebase para uma atualização em lote.

Nesses casos, use firebase dataconnect:sdk:generate.

Inicializar o SDK do iOS Data Connect

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

Como conseguir uma instância de 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, recupere o objeto do conector chamando:

let connector = DataConnect.moviesConnector

Implementar consultas e mutações

Com o objeto conector, é possível executar consultas e mutações conforme definido no código-fonte GraphQL. Suponha que seu 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, você vai usar uma referência de consulta. Todas as referências de consulta são publishers observáveis. Dependendo do editor configurado (consulte connector.yaml)), eles oferecem suporte à macro @Observable (iOS 17 ou mais recente) ou implementam o protocolo ObservableObject. O padrão, se nenhum for especificado, é a macro @Observable compatível com o iOS 17 e versões mais recentes.

Em uma visualização do 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 ao formato dos dados definidos na definição da consulta GQL.

Todos os resultados recuperados estão em conformidade com o protocolo Decodable. Se você incluiu a chave primária do objeto na busca de 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 são compatíveis com a execução única.

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

Desenvolver 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 VS Code ou na CLI.

A instrumentação do app para se conectar ao emulador é a mesma nos 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 Data Connect

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