Firebase Data Connect client SDKs let you call your server-side queries and mutations directly from a Firebase app. You generate a custom client SDK in parallel as you design the schemas, queries and mutations you deploy to your Data Connect service. Then, you integrate methods from this SDK into your client logic.
As we've mentioned elsewhere, it's important to note that Data Connect queries and mutations are not submitted by client code and executed on the server. Instead, when deployed, Data Connect operations are stored on the server like Cloud Functions. This means you need to deploy corresponding client-side changes to avoid breaking existing users (for example, on older app versions).
That's why Data Connect provides you with a developer environment and tooling that lets you prototype your server-deployed schemas, queries and mutations. It also generates client-side SDKs automatically, while you prototype.
When you've iterated updates to your service and client apps, both server- and client-side updates are ready to deploy.
Generate your Kotlin SDK
As with most Firebase projects, work on your Firebase Data Connect client code takes place in a local project directory. Both the Data Connect VS Code extension and the Firebase CLI are important local tools for generating and managing client code.
SDK generation options are keyed to several entries in the dataconnect.yaml
file generated when you initialized your project.
Initialize SDK generation
In yourconnector.yaml
, add your outputDir
, package
and (for the web SDK)
packageJsonDir
.
connectorId: movies
generate:
kotlinSdk:
outputDir: ../../../src/main/java/com/myapplication
package: com.myapplication
Replace outputDir
with the path of the directory into which the generated
code will be placed; this path is relative to the directory that contains the
connector.yaml
file itself. Replace package
with the Kotlin package
statement to be used in the generated files, or omit package
to use a default
package.
Update SDKs while prototyping
If you're prototyping interactively with the Data Connect VS Code extension
and its Data Connect emulator, SDK source files are automatically
generated and updated while you modify .gql
files defining schemas, queries
and mutations. This can be a useful feature in hot (re)loading workflows.
.gql
updates and also have SDK
sources automatically updated.
Alternatively, you can use the CLI to regenerate SDKs whenever .gql files are changed:
firebase dataconnect:sdk:generate --watch
Generate SDKs for integration and for production releases
In some scenarios, such as preparing project sources to submit for CI tests, you can call the Firebase CLI for a batch update.
In these cases, use firebase dataconnect:sdk:generate
.
Set up client code
Incorporate Data Connect into your client code
To set up your client code to use Data Connect and your generated SDK, first follow the standard Firebase setup instructions.
Then, add the following into the plugins
section in
app/build.gradle.kts
:
// The Firebase team tests with version 1.8.22; however, other 1.8 versions,
// and all newer versions are expected work too.
kotlin("plugin.serialization") version "1.8.22" // MUST match the version of the Kotlin compiler
Then, add the following into the dependencies
section in
app/build.gradle.kts
:
implementation("com.google.firebase:firebase-dataconnect:16.0.0-beta01")
implementation("org.jetbrains.kotlinx:kotlinx-coroutines-core:1.7.3")
implementation("org.jetbrains.kotlinx:kotlinx-serialization-core:1.5.1")
implementation("com.google.firebase:firebase-auth:23.0.0") // Optional
implementation("com.google.firebase:firebase-appcheck:18.0.0") // Optional
Initialize the Data Connect Android SDK
Initialize your Data Connect instance using the information you used to set up Data Connect (all available in the Firebase console Data Connect tab).
The ConnectorConfig object
The SDK requires a connector configuration object.
This object is automatically generated from serviceId
and location
in
dataconnect.yaml
, and connectorId
in connector.yaml
.
Getting a connector instance
Now that you've set up a configuration object, get a Data Connect
connector instance. The code for your connector will be generated by the
Data Connect emulator. If your connector name is movies
and the
Kotlin package is com.myapplication
, as specified in connector.yaml
, then
retrieve the connector object by calling:
val connector = com.myapplication.MoviesConnector.instance
Run queries and mutations
With the connector object, you can run queries and mutations as defined in the GraphQL source code. Suppose your connector has these operations defined:
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
}
}
then you could create and retrieve a movie as follows:
val connector = MoviesConnector.instance
val addMovieResult1 = connector.createMovie.execute(
title = "Empire Strikes Back",
releaseYear = 1980,
genre = "Sci-Fi",
rating = 5
)
val movie1 = connector.getMovieByKey.execute(addMovieResult1.data.key)
println("Empire Strikes Back: ${movie1.data.movie}")
You can also retrieve multiple movies:
val connector = MoviesConnector.instance
val addMovieResult2 = connector.createMovie.execute(
title="Attack of the Clones",
releaseYear = 2002,
genre = "Sci-Fi",
rating = 5
)
val listMoviesResult = connector.listMoviesByGenre.execute(genre = "Sci-Fi")
println(listMoviesResult.data.movies)
You can also collect a Flow
that will only produce a result when a new query
result is retrieved using a call to the query's execute()
method.
val connector = MoviesConnector.instance
connector.listMoviesByGenre.flow(genre = "Sci-Fi").collect { data ->
println(data.movies)
}
connector.createMovie.execute(
title="A New Hope",
releaseYear = 1977,
genre = "Sci-Fi",
rating = 5
)
connector.listMoviesByGenre.execute(genre = "Sci-Fi") // will cause the Flow to get notified
Prototype and test your Android application
Instrument clients to use a local emulator
You can use the Data Connect emulator, whether from the Data Connect VS Code extension or from the CLI.
Instrumenting the app to connect to the emulator is the same for both scenarios.
val connector = MoviesConnector.instance
// Connect to the emulator on "10.0.2.2:9399"
connector.dataConnect.useEmulator()
// (alternatively) if you're running your emulator on non-default port:
connector.dataConnect.useEmulator(port = 9999)
// Make calls from your app
To switch to production resources, comment out lines for connecting to the emulator.
Data types in Data Connect SDKs
The Data Connect server represents common and custom GraphQL data types. These are represented in the SDK as follows.
Data Connect Type | Kotlin |
---|---|
String | String |
Int | Int (32-bit) |
Float | Double (64-bit float) |
Boolean | Boolean |
UUID | java.util.UUID |
Date | java.util.Date |
Timestamp | com.google.firebase.Timestamp |
Int64 | Long |
Any | com.google.firebase.dataconnect.AnyValue |