Usar SDKs do iOS gerados

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

Como já mencionamos, é importante observar que as Data Connect consultas e mutações 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 que os usuários atuais (por exemplo, em versões mais antigas do app sejam afetados).

É por isso que Data Connect oferece um ambiente de desenvolvedor 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 durante a criação do protótipo.

Quando você tiver atualizado os apps de serviço e cliente, as atualizações do servidor e do cliente estarão prontas para implantação.

Qual é o fluxo de trabalho de desenvolvimento do cliente?

Se você seguiu o guia de introdução, já conhece o fluxo de desenvolvimento geral do Data Connect. Neste guia, você vai encontrar informações mais detalhadas sobre como gerar SDKs do Swift com base no esquema e trabalhar com consultas e mutações do cliente.

Para resumir, siga estas etapas necessárias para usar os SDKs do Swift gerados nos apps de cliente:

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 File > Add Package Dependencies > Add Local e escolha a pasta que contém o Package.swift gerado.

Em seguida:

1. Desenvolva o esquema do app.

2. Configure a geração do SDK:

   • Com o botão Add SDK to app na extensão do Data Connect VS Code
   • Ao atualizar seu connector.yaml

3. Inicialize o código do cliente e importe 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

Use a Firebase CLI para configurar os Data Connect gerados nos seus apps. O comando init detecta todos os apps na pasta atual e instala os SDKs gerados automaticamente.

firebase init dataconnect:sdk

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

Se você tiver a extensão do Data Connect VS Code instalada, ela sempre vai manter os SDKs gerados atualizados.

Se você não usa a extensão do Data Connect VS Code, pode usar a CLI do Firebase para manter os SDKs gerados atualizados.

firebase dataconnect:sdk:generate --watch

Gerar SDKs em pipelines de build

Você pode usar a CLI do Firebase para gerar SDKs do Data Connect em processos de build de CI/CD.

firebase dataconnect:sdk:generate

Inicializar o Data Connect SDK para iOS

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

Como conseguir uma instância do conector

O código do conector será gerado pelo Data Connect emulador. 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 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, você pode criar 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), eles oferecem suporte à @Observable macro (iOS 17 e versões mais recentes) ou implementam o ObservableObject protocolo. O padrão, se nenhum for especificado, é a @Observable macro com suporte no iOS 17 e versões mais recentes.

Em uma visualização do SwiftUI, é possível vincular os resultados da consulta usando a data variável publicada da referência da 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 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")

Processar mudanças nos campos de enumeração

O esquema de um app pode conter enumerações, que podem ser acessadas pelas suas consultas do GraphQL.

À medida que o design de um app muda, você pode adicionar novos valores com suporte para enumeração. Por exemplo, imagine que, mais tarde no ciclo de vida do aplicativo, você decida adicionar um valor FULLSCREEN à enumeração AspectRatio.

No fluxo de trabalho Data Connect, é possível usar ferramentas de desenvolvimento local para atualizar consultas e SDKs.

No entanto, antes de lançar uma versão atualizada dos clientes, os clientes implantados mais antigos podem ser interrompidos.

Exemplo de implementação resiliente

O SDK gerado força o processamento de valores desconhecidos, já que as enumerações geradas contêm um _UNKNOWN valor, e o Swift impõe instruções de troca exaustivas.

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
}

Criar protótipos e testar o aplicativo iOS

Instrumentar clientes para usar um emulador local

Você pode usar o Data Connect emulador, seja na extensão do Data Connect 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 Data Connect SDKs

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