You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
@@ -29,19 +29,126 @@ The following libraries are available for the various Firebase products.
29
29
30
30
Is the Firebase library or API you need missing? [Create an issue](https://github.com/GitLiveApp/firebase-kotlin-sdk/issues/new?labels=API+coverage&template=increase-api-coverage.md&title=Add+%5Bclass+name%5D.%5Bfunction+name%5D+to+%5Blibrary+name%5D+for+%5Bplatform+names%5D) to request additional API coverage or be awesome and [submit a PR](https://github.com/GitLiveApp/firebase-kotlin-sdk/fork)
31
31
32
+
## Installation
33
+
1. First of all, Add `plugin.serialization` plugin in gradle:
34
+
* First go to `build.gradle.kts` in the main root folder and add it:
35
+
36
+
```groovy
37
+
kotlin("plugin.serialization").version("1.9.20").apply(false) // use the latest version of kotlin
38
+
```
39
+
40
+
* Then go to `build.gradle.kts` in the shared module:
41
+
42
+
```groovy
43
+
kotlin("plugin.serialization")
44
+
```
45
+
2. Choose the Firebase products you are going to use, in this example, we will use only `firestore` but you can use more
46
+
Start By adding the dependency `dev.gitlive:firebase-firestore` in the `commonMain` in the `sourceSets` block which exists usually in `kotlin` and you will find it in `build.gradle.kts` in the shared module:
You don't have to add all the libraries you are going to use, like Firebase Firestore `com.google.firebase:firebase-firestore-ktx`
95
+
because it's already there when you add the Firebase Firestore KMP SDK in the `commonMain`, but you can if you planning on using the code in the `androidMain` or `androidApp`
96
+
97
+
### iOS
98
+
* You need to add the official [iOS Firebase SDK](https://firebase.google.com/docs/ios/setup) first, there a different ways to get it, check this [installation guide](https://firebase.google.com/docs/ios/installation-methods) but the easiest way is using swift package manager, you can also using `Cocoapods`
99
+
* in `iOSApp.swift` or your main app file
100
+
Import the Firebase Core
101
+
```swift
102
+
import SwiftUI
103
+
import FirebaseCore
104
+
```
105
+
* Create `AppDelegate` that initializes the Firebase iOS SDK using
106
+
```swift
107
+
FirebaseApp.configure()
108
+
```
109
+
and add it to your app
110
+
111
+
example of what it will look like:
112
+
113
+
```swift
114
+
import SwiftUI
115
+
import FirebaseCore
116
+
117
+
class AppDelegate: NSObject, UIApplicationDelegate {
@UIApplicationDelegateAdaptor(AppDelegate.self) var delegate
129
+
var body: some Scene {
130
+
WindowGroup {
131
+
ContentView()
132
+
}
133
+
}
134
+
}
135
+
136
+
```
137
+
138
+
32
139
## Kotlin-first design
33
140
34
-
Unlike the Kotlin Extensions for the Firebase Android SDK this project does not extend a Javabased SDK so we get the full power of Kotlin including coroutines and serialization!
141
+
Unlike the Kotlin Extensions for the Firebase Android SDK, this project does not extend a Java-based SDK so we get the full power of Kotlin including coroutines and serialization!
Asynchronous operations that return a single or no value are represented by suspending functions in the SDK instead of callbacks, listeners or OSspecific types such as [Task](https://developer.android.com/reference/com/google/android/play/core/tasks/Task), for example:
145
+
Asynchronous operations that return a single or no value are represented by suspending functions in the SDK instead of callbacks, listeners, or OS-specific types such as [Task](https://developer.android.com/reference/com/google/android/play/core/tasks/Task), for example:
39
146
40
147
```kotlin
41
148
suspend fun signInWithCustomToken(token: String): AuthResult
42
149
```
43
150
44
-
It is important to remember that unlike a callbackbased API, wating for suspending functions to complete is implicit and so if you don't want to wait for the result you can `launch` a new coroutine:
151
+
It is important to remember that, unlike a callback-based API, waiting for suspending functions to complete is implicit so if you don't want to wait for the result you can `launch` a new coroutine:
45
152
46
153
```kotlin
47
154
//TODO don't use GlobalScope
@@ -58,24 +165,17 @@ Asynchronous streams of values are represented by Flows in the SDK instead of re
58
165
val snapshots:Flow<DocumentSnapshot>
59
166
```
60
167
61
-
The flows are cold, which means a new listener is added every time a terminal operator is applied to the resulting flow. A buffer with the [default size](https://kotlin.github.io/kotlinx.coroutines/kotlinx-coroutines-core/kotlinx.coroutines.channels/-channel/-b-u-f-f-e-r-e-d.html) is used to buffer values received from the listener, use the [`buffer` operator](https://kotlin.github.io/kotlinx.coroutines/kotlinx-coroutines-core/kotlinx.coroutines.flow/buffer.html) on the flow to specify a user-defined value and to control what happens when data is produced faster than consumed, i.e. to control the back-pressure behavior. Often you are only interested in the latest value received, in this case you can use the [`conflate` operator](https://kotlin.github.io/kotlinx.coroutines/kotlinx-coroutines-core/kotlinx.coroutines.flow/conflate.html) to disable buffering.
168
+
The flows are cold, which means a new listener is added every time a terminal operator is applied to the resulting flow. A buffer with the [default size](https://kotlin.github.io/kotlinx.coroutines/kotlinx-coroutines-core/kotlinx.coroutines.channels/-channel/-b-u-f-f-e-r-e-d.html) is used to buffer values received from the listener, use the [`buffer` operator](https://kotlin.github.io/kotlinx.coroutines/kotlinx-coroutines-core/kotlinx.coroutines.flow/buffer.html) on the flow to specify a user-defined value and to control what happens when data is produced faster than consumed, i.e. to control the back-pressure behavior. Often you are only interested in the latest value received, in this case, you can use the [`conflate` operator](https://kotlin.github.io/kotlinx.coroutines/kotlinx-coroutines-core/kotlinx.coroutines.flow/conflate.html) to disable buffering.
62
169
63
170
The listener is removed once the flow [completes](https://kotlinlang.org/docs/reference/coroutines/flow.html#flow-completion) or is [cancelled](https://kotlinlang.org/docs/reference/coroutines/flow.html#flow-cancellation).
The official Firebase SDKs use different platform-specific ways to support writing data with and without custom classes in [Cloud Firestore](https://firebase.google.com/docs/firestore/manage-data/add-data#custom_objects), [Realtime Database](https://firebase.google.com/docs/database/android/read-and-write#basic_write) and [Functions](https://firebase.google.com/docs/functions/callable).
68
175
69
-
The Firebase Kotlin SDK uses Kotlin serialization to read and write custom classes to Firebase. To use Kotlin serialization in your project add the plugin to your gradle file:
70
-
71
-
```groovy
72
-
plugins {
73
-
kotlin("multiplatform") version "1.8.20" // or kotlin("jvm") or any other kotlin plugin
74
-
kotlin("plugin.serialization") version "1.8.20"
75
-
}
76
-
```
176
+
The Firebase Kotlin SDK uses Kotlin serialization to read and write custom classes for Firebase. To use Kotlin serialization in your project, follow the instructions in the installation for the Kotlin serialization
77
177
78
-
Then mark you custom classes `@Serializable`:
178
+
Then mark your custom classes `@Serializable`:
79
179
80
180
```kotlin
81
181
@Serializable
@@ -88,7 +188,7 @@ Instances of these classes can now be passed [along with their serializer](https
88
188
db.collection("cities").document("LA").set(City.serializer(), city, encodeDefaults =true)
89
189
```
90
190
91
-
The `encodeDefaults` parameter is optional and defaults to `true`, set this to false to omit writing optional properties if they are equal to theirs default values.
191
+
The `encodeDefaults` parameter is optional and defaults to `true`, set this to false to omit writing optional properties if they are equal to their default values.
92
192
Using [@EncodeDefault](https://kotlinlang.org/api/kotlinx.serialization/kotlinx-serialization-core/kotlinx.serialization/-encode-default/) on properties is a recommended way to locally override the behavior set with `encodeDefaults`.
93
193
94
194
You can also omit the serializer but this is discouraged due to a [current limitation on Kotlin/JS and Kotlin/Native](https://github.com/Kotlin/kotlinx.serialization/issues/1116#issuecomment-704342452)
@@ -129,7 +229,7 @@ val document = PointOfInterest(
This sdk will handle polymorphic serialization automatically if you have a sealed class and its children marked as `Serializable`. It will include a `type` property that will be used to discriminate which child class is the serialized.
232
+
This SDK will handle polymorphic serialization automatically if you have a sealed class and its children are marked as `Serializable`. It will include a `type` property that will be used to discriminate which child class is serialized.
133
233
134
234
You can change this `type` property by using the `@FirebaseClassDiscrminator` annotation in the parent sealed class:
135
235
@@ -204,15 +304,15 @@ In cases where it makes sense, such as Firebase Functions HTTPS Callable, operat
204
304
205
305
## Multiplatform
206
306
207
-
The Firebase Kotlin SDK provides a common API to access Firebase for projects targeting *iOS*, *Android* and *JS* meaning you can use Firebase directly in your common code. Under the hood, the SDK achieves this by binding to the respective official Firebase SDK for each supported platform.
307
+
The Firebase Kotlin SDK provides a common API to access Firebase for projects targeting *iOS*, *Android*, and *JS* meaning you can use Firebase directly in your common code. Under the hood, the SDK achieves this by binding to the respective official Firebase SDK for each supported platform.
208
308
209
309
It uses the <ahref="https://github.com/GitLiveApp/firebase-java-sdk">Firebase Java SDK</a> to support the JVM target.
210
310
211
311
### Accessing the underlying Firebase SDK
212
312
213
-
In some cases you might want to access the underlying official Firebase SDK in platformspecific code, for example when the common API is missing the functionality you need. For this purpose each class in the SDK has `android`, `ios` and `js` properties which holds the equivalent object of the underlying official Firebase SDK.
313
+
In some cases, you might want to access the underlying official Firebase SDK in platform-specific code, for example when the common API is missing the functionality you need. For this purpose, each class in the SDK has `android`, `ios`, and `js` properties which hold the equivalent object of the underlying official Firebase SDK.
214
314
215
-
These properties are only accessible from the equivalent target's source set. For example to disable persistence in Cloud Firestore on Android you can write the following in your Androidspecific code (e.g. `androidMain` or `androidTest`):
315
+
These properties are only accessible from the equivalent target's source set. For example, to disable persistence in Cloud Firestore on Android you can write the following in your Android-specific code (e.g. `androidMain` or `androidTest`):
0 commit comments