Utiliser les SDK iOS générés

Les SDK client Firebase Data Connect vous permettent d'appeler vos requêtes et mutations côté serveur directement depuis une application Firebase. Vous générez un SDK client personnalisé en parallèle de la conception des schémas, des requêtes et des mutations que vous déployez sur votre service Firebase Data Connect.Data Connect Ensuite, vous intégrez les méthodes de ce SDK dans la logique de votre client.

Comme nous l'avons mentionné ailleurs, il est important de noter que les requêtes et les mutations Data Connectne sont pas envoyées par le code client et exécutées sur le serveur. En revanche, une fois déployées, les opérations Data Connect sont stockées sur le serveur, comme Cloud Functions. Cela signifie que vous devez déployer les modifications correspondantes côté client pour éviter de perturber les utilisateurs existants (par exemple, sur les anciennes versions de l'application).

C'est pourquoi Data Connect vous fournit un environnement de développement et des outils qui vous permettent de prototyper vos schémas, requêtes et mutations déployés sur le serveur. Il génère également automatiquement des SDK côté client pendant que vous créez votre prototype.

Une fois que vous avez effectué des mises à jour itératives de vos applications de service et client, les mises à jour côté serveur et côté client sont prêtes à être déployées.

Qu'est-ce que le workflow de développement client ?

Si vous avez suivi la section Premiers pas, vous avez découvert le flux de développement global pour Data Connect. Dans ce guide, vous trouverez des informations plus détaillées sur la génération de SDK Swift à partir de votre schéma, ainsi que sur l'utilisation des requêtes et des mutations client.

Vous pouvez apprendre à développer des clients avec un dépôt d'application de démarrage rapide et créer une application Data Connect complète en suivant notre atelier de programmation pour iOS.

En résumé, pour utiliser les SDK Swift générés dans vos applications clientes, vous devez suivre les étapes préalables suivantes :

1. Ajoutez Firebase à votre application iOS.

2. Pour utiliser le SDK généré, configurez-le comme dépendance dans Xcode.

   Dans la barre de navigation supérieure d'Xcode, sélectionnez File > Add Package Dependencies > Add Local (Fichier > Ajouter des dépendances de package > Ajouter localement), puis choisissez le dossier contenant le fichier Package.swift généré.

Puis :

1. Développez le schéma de votre application.

2. Configurez la génération du SDK :

   • Avec le bouton Ajouter le SDK à l'application de notre extension VS Code Data Connect
   • En mettant à jour votre connector.yaml

3. Initialisez votre code client et importez les bibliothèques.

4. Implémentez les appels aux requêtes et aux mutations.

5. Configurez et utilisez l'émulateur Data Connect, puis itérez.

Générer votre SDK Swift

Utilisez l'interface de ligne de commande Firebase pour configurer les SDK générés Data Connect dans vos applications. La commande init devrait détecter toutes les applications du dossier actuel et installer automatiquement les SDK générés.

firebase init dataconnect:sdk

Mettre à jour les SDK lors du prototypage

Si l'extension VS Code Data Connect est installée, elle maintient toujours les SDK générés à jour.

Si vous n'utilisez pas l'extension VS Code Data Connect, vous pouvez utiliser la CLI Firebase pour maintenir à jour les SDK générés.

firebase dataconnect:sdk:generate --watch

Générer des SDK dans des pipelines de compilation

Vous pouvez utiliser la CLI Firebase pour générer des SDK Data Connect dans les processus de compilation CI/CD.

firebase dataconnect:sdk:generate

Initialiser le SDK iOS Data Connect

Initialisez votre instance Data Connect à l'aide des informations que vous avez utilisées pour configurer Data Connect (toutes disponibles dans l'onglet "Data Connect" de la console Firebase).

Obtenir une instance de connecteur

Le code de votre connecteur sera généré par l'émulateur Data Connect. Si le nom de votre connecteur est movies et que le package est movies, comme spécifié dans connector.yaml, récupérez l'objet du connecteur en appelant :

let connector = DataConnect.moviesConnector

Implémenter des requêtes et des mutations

L'objet de connecteur vous permet d'exécuter des requêtes et des mutations telles que définies dans le code source GraphQL. Supposons que votre connecteur comporte les opérations suivantes :

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

Vous pouvez ensuite créer un film comme suit :

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

Pour récupérer un film, vous devez utiliser une référence de requête. Toutes les références de requête sont des éditeurs observables. Selon l'éditeur configuré (voir connector.yaml)), il prend en charge la macro @Observable (iOS 17+) ou implémente le protocole ObservableObject. Si aucune valeur n'est spécifiée, la valeur par défaut est la macro @Observable compatible avec iOS 17 et versions ultérieures.

Dans une vue SwiftUI, vous pouvez associer les résultats de la requête à l'aide de la variable data publiée de la référence de requête et appeler la méthode execute() de la requête pour mettre à jour les données. La variable data correspondra à la forme des données définies dans votre définition de requête GQL.

Tous les résultats récupérés sont conformes au protocole Decodable. Si vous avez inclus la clé primaire de l'objet dans votre récupération GQL, les objets sont également Identifiable, ce qui vous permet de les utiliser dans des itérateurs.

Remarque : Le @StateObject n'est pas mis à jour en temps réel. Elle n'est pas non plus nécessaire lorsque vous utilisez une macro @Observable en tant qu'éditeur.

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

Les requêtes sont également compatibles avec l'exécution unique.

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

Gérer les modifications apportées aux champs d'énumération

Le schéma d'une application peut contenir des énumérations, auxquelles vos requêtes GraphQL peuvent accéder.

À mesure que la conception d'une application change, vous pouvez ajouter de nouvelles valeurs d'énumération acceptées. Par exemple, imaginez que vous décidiez d'ajouter une valeur FULLSCREEN à l'énumération AspectRatio plus tard dans le cycle de vie de votre application.

Dans le workflow Data Connect, vous pouvez utiliser des outils de développement local pour mettre à jour vos requêtes et vos SDK.

Toutefois, avant de publier une version mise à jour de vos clients, il est possible que les anciens clients déployés ne fonctionnent plus.

Exemple d'implémentation résiliente

Le SDK généré force la gestion des valeurs inconnues, car les énumérations générées contiennent une valeur _UNKNOWN et Swift applique des instructions switch exhaustives.

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
}

Prototyper et tester votre application iOS

Instrumenter les clients pour qu'ils utilisent un émulateur local

Vous pouvez utiliser l'émulateur Data Connect, que ce soit à partir de l'extension VS Code Data Connect ou de la CLI.

L'instrumentation de l'application pour se connecter à l'émulateur est la même dans les deux scénarios.

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

Types de données dans les SDK Data Connect

Le serveur Data Connect représente les types de données GraphQL courants et personnalisés. Elles sont représentées dans le SDK comme suit.

Type de connexion de données	Swift
Chaîne	Chaîne
Int	Int
Float	Double
Booléen	Bool
UUID	UUID
Date	FirebaseDataConnect.LocalDate
Horodatage	FirebaseCore.Timestamp
Int64	Int64
Tous	FirebaseDataConnect.AnyValue