English | 한국어

A Kotlin Multiplatform (KMP) wrapper around Firebase platform SDKs, designed to expose native Kotlin-first APIs for Android and iOS projects.

• Kotlin-First Design: Native support for Coroutines (suspend functions) and asynchronous stream processing (Flow).
• Thin & Light Adaption: Implements clean expect/actual wrappers that delegate directly to official Firebase Android (GMS/Maven) and iOS (Apple SwiftPM) SDKs.
• Platform Integrity: Unsupported iOS platform features gracefully fallback with descriptive stubs rather than crashing on build time.

Android versions are read from gradle/libs.versions.toml; BoM-managed rows use Firebase Android BoM 34.16.0. iOS native rows use Firebase Apple SDK 12.14.0; rows marked Memory actual do not link the native Apple SDK from common KMP code.

Add the core dependency to your shared Kotlin Multiplatform module's build.gradle.kts:

kotlin {
    sourceSets {
        commonMain.dependencies {
            // Core Common Firebase APIs
            implementation("zone.ien.firebase:firebase-common:1.0.0-beta03")
            
            // Add required feature wrappers
            implementation("zone.ien.firebase:firebase-auth:1.0.0-beta03")
            implementation("zone.ien.firebase:firebase-firestore:1.0.0-beta03")
        }
    }
}

Ensure your root build.gradle.kts applies the Google Services plugin, and your app-level module imports the configuration file (google-services.json).

This library uses native Swift Package Manager linkage for Apple builds. Make sure the native Xcode package dependencies are resolved during the build pipeline:

# Resolve SPM dependencies under the iOS build step
xcodebuild -resolvePackageDependencies -workspace iosApp.xcworkspace -scheme iosApp

[!IMPORTANT] Minimum Kotlin Version: This SwiftPM import feature relies on the official Swift Package Manager integration introduced in Kotlin 2.4.0 (utilizing the new native swiftPMDependencies DSL). Therefore, Kotlin 2.4.0 or higher is strictly required as the minimum compiler version to compile and link this library's iOS targets.

The repository includes a Kotlin Multiplatform Compose sample application located in the example directory.

To build and run the sample application successfully, you must provide your own Firebase configuration files:

1. Android: Place your own google-services.json inside the example/androidApp/ directory.
2. iOS: Add your own GoogleService-Info.plist to the example/iosApp/ project (typically inside the iosApp/ folder and registered in Xcode).

The Firestore sample screen now includes an executable query testing panel. It auto-seeds the query_samples collection with documents containing name, score, age, category, tags, and createdAt, then lets you run where, orderBy, limit, limitToLast, and document-cursor pagination checks directly from the sample app.

Initialize the Firebase SDK using your platform context:

import zone.ien.firebase.Firebase
import zone.ien.firebase.initialize

// Initialize Firebase Core
val app = Firebase.initialize(context) // FirebasePlatformContext

Interact with Firestore collection documents and query builders natively:

import zone.ien.firebase.firestore.firestore
import zone.ien.firebase.Firebase

val db = Firebase.firestore
val document = db.collection("users").document("user_id")

// Set Data asynchronously
document.set(mapOf("name" to "John Doe", "age" to 30))

// Get Data natively via Kotlin Coroutines
val snapshot = document.get()
val userName = snapshot.get<String>("name")

// Run a query with where, orderBy, and limit.
val users = db.collection("users")
    .where("age", WhereOperator.GREATER_THAN_OR_EQUAL, 21)
    .orderBy("score", QueryDirection.DESCENDING)
    .limit(10)
    .get()

Supported query wrappers currently include equality, inequality, comparison (<, <=, >, >=), array-contains, array-contains-any, in, not-in, ascending/descending orderBy, limit, limitToLast, and document snapshot cursors (startAt, startAfter, endAt, endBefore). Android and iOS delegate these calls to the official Firebase SDKs. Unsupported Firestore combinations, missing composite indexes, and platform SDK errors are surfaced to callers and shown in the sample app.

1. Developers transitionally upgrading from native GMS Android SDKs to Kotlin Multiplatform.
2. Teams migrating from alternative KMP wrappers (e.g. GitLive's firebase-kotlin-sdk) seeking explicit stub fallbacks for unsupported iOS architectures.

Rename your packaging imports to adapt to this SDK's namespaces:

• Synchronous vs Asynchronous Task Mappings: Android-specific Task<T> and callback models are mapped to standard Kotlin suspend functions returning T directly.
• Real-time Event Observers: Event listeners are exposed as pure Kotlin Flow<T> streams. Replace older callback attachments with .collect { ... } blocks inside your Coroutine lifecycle.
• Elimination of iOS Unsupported Stubs (Memory-based Actual): To prevent compilation failure and runtime crashes (UnsupportedOperationException), several modules (such as AI Logic, Data Connect, ML Model Downloader, etc.) have been migrated to "Memory-based Actuals". These implementations store states and subscriber callbacks locally in memory to preserve API visibility and call flow safety.
• Messaging bridge: messages is process-global, while Android tokenUpdates replay state is isolated by Firebase app identity. Enable the optional FirebaseMessagingService with firebase_messaging_service_enabled=true, or forward an existing service's callbacks through FirebaseMessagingServiceBridge; onNewToken updates the default app. On iOS, tokenUpdates remains default-app only, and the host app must convert APNs userInfo with remoteMessageFromUserInfo before calling handleMessage.
• Installations timestamp contract: tokenExpirationTimestamp and tokenCreationTimestamp are Unix epoch milliseconds; the explicit ...TimestampMillis aliases expose the same values. Android duration/epoch seconds are normalized at the platform boundary. hasTokenCreationTimestamp is false on iOS because the Apple result does not expose creation time.
• A/B Testing application status: Android creates the official ABT component for the fixed frc or fiam origin and applies validated experiments. iOS records the requested experiments and reports RECORDED_NOT_APPLIED; it does not apply native experiments.
• In-App Messaging Display models: Android and iOS custom display delegates convert native card, banner, modal, and image-only messages to the typed common display model and forward display callbacks.

Google's native iOS SDKs for Gemini AI, Data Connect, and Custom Model Downloader are written purely in Swift without Objective-C bridge headers. Since Kotlin/Native's cinterop pipeline cannot generate bindings directly for Swift-only frameworks, the iOS source set implementations for these features operate in a virtualized simulation mode (Memory-based Actual). This allows listener registrations and local configurations to compile and run without crashes, while actual remote connections or native rendering must be implemented inside your iOS target codebase. (※ Note: In-App Messaging Core and custom-display delegate APIs operate on iOS through native typed models.)

1. Authentication Redirect (URL Schemes Required): To safely redirect back to the app after tester OAuth sign-in on iOS, you must register the REVERSED_CLIENT_ID found in your GoogleService-Info.plist (e.g., com.googleusercontent.apps.xxxx-xxxx) as a URL Scheme in your Info.plist.
2. App Delegate Swizzling Bypass: If App Delegate Swizzling is disabled (FirebaseAppDelegateProxyEnabled is set to false in your Info.plist), you must manually forward the incoming deep link URL to App Distribution inside your AppDelegate: AppDistribution.appDistribution().application(app, open: url, options: options)
3. In-App Update Progress Monitoring Unsupported: The iOS Firebase SDK does not expose stream listeners for download progress (bytes completed). Calling updateIfNewReleaseAvailable throws UnsupportedOperationException. Instead, checking for releases automatically triggers the iOS SDK's built-in update alert dialog, guiding the user to Safari/TestFlight.

1. Swift-only Library Limitation: The official iOS FirebaseDataConnect SDK is written strictly in Swift and lacks Objective-C compatibility headers. Consequently, Kotlin/Native cinterop cannot parse the headers or link the binary target.
2. KMP Memory-based Actual: The iOS connector can execute only a seededQuery from its local memory cache and marks that result as MEMORY. SERVER_ONLY queries and every mutation complete with the BRIDGE_REQUIRED failure kind; they do not contact Data Connect.
3. Live GraphQL Queries: To execute server queries or mutations on iOS, call the Firebase CLI-generated client SDK from native iOS Swift code rather than KMP common code.

Common code consumes a generated/platform descriptor through the factory itself:

suspend fun <Data, Variables> executeFromCommon(
    connector: FirebaseDataConnectConnector,
    descriptor: DataConnectQueryDescriptor<Data, Variables>,
    variables: Variables
): Data = connector.operations
    .query(descriptor)
    .ref(variables)
    .execute()
    .data

Android generated operations are converted with queryDescriptor(...) / mutationDescriptor(...). The iOS memory adapter supplies seeded descriptors; it never reports a fabricated server success.

1. Binary Linkage & Infrastructure Execution: The Firebase Sessions SDK is an internal-only telemetry backend SDK that exposes almost no public APIs for manual code interaction. Through this migration, the FirebaseSessions SwiftPM product is now fully linked during the iOS compilation pipeline.
2. KMP Role & Auto-Association: The FirebaseSessions expect/actual mapping guarantees classpath availability inside common source sets. Session ID lifecycle analytics are automatically recorded in the background on iOS, associating silently with both the Crashlytics and Performance Monitoring SDKs.

1. Swift-only Library Limitation: The official iOS FirebaseMLModelDownloader SDK is written strictly in Swift and lacks Objective-C compatibility headers. Consequently, Kotlin/Native cinterop cannot parse the headers or link the binary target.
2. KMP Memory-based Actual: To prevent compilation failure and runtime crashes, the iOS actual implementation for Model Downloader operates in "Memory-only container mode". Requesting a model (getModel), listing downloaded models (listDownloadedModels), and deleting models (deleteDownloadedModel) store and verify states safely inside a local memory registry.
3. Live Model Downloads: To physically download custom TFLite model files on iOS, you must call the Firebase ML Swift SDK directly from your native iOS Swift codebase, rather than KMP common code.

1. Swift-only Library Limitation: The official iOS FirebaseAILogic SDK is written strictly in Swift and lacks Objective-C compatibility headers. Consequently, Kotlin/Native cinterop cannot parse the headers or link the binary target.
2. KMP Memory-based Actual: To prevent compilation failure and runtime crashes, the iOS actual implementation for AI Logic operates in "Memory-only container mode". Requesting a model (generativeModel) and dispatching content generation (generateContent) simulate a 1.5s network delay and return a simulated reply including prompt parameters safely.
3. Live AI Requests: To connect to live Vertex AI backend services on iOS, you must call the official Firebase AI Swift SDK directly from your native iOS Swift codebase, rather than KMP common code.

1. Swift-only Library Limitation: The official iOS on-device/hybrid AI SDK (supporting Apple Intelligence) is written strictly in Swift and lacks Objective-C compatibility headers. Consequently, Kotlin/Native cinterop cannot parse the headers or link the binary target.
2. KMP Memory-based Actual: To prevent compilation failure and runtime crashes, the iOS actual implementation for AI On-Device operates in "Memory-only container mode". Instantiating generativeModel with OnDeviceConfig and calling generateContent(prompt) parse the local InferenceMode (PREFER_ON_DEVICE, PREFER_IN_CLOUD, ONLY_ON_DEVICE) configuration safely inside a local memory simulation.
3. Live On-Device AI Requests: To utilize live Apple Intelligence on-device inference or hybrid fallbacks on iOS, you must call the official Firebase AI Swift SDK directly from your native iOS Swift codebase, rather than KMP common code.

Action Needed: Guard your UI entry points or calls to these services on iOS:

import zone.ien.firebase.example.util.isIos

if (!isIos) {
    // Safely run Android-supported AI logic
    Firebase.ai.generativeModel("gemini-3.5-flash").generateContent(prompt)
} else {
    // Display unsupported fallback notice
}

Copyright (c) 2026. Firebase Kotlin SDK project and open source contributors.
Copyright (c) 2026. IENGROUND of IENLAB.

Licensed under the Apache License, Version 2.0 (the "License");
you may not use this file except in compliance with the License.
You may obtain a copy of the License at

    http://www.apache.org/licenses/LICENSE-2.0

Unless required by applicable law or agreed to in writing, software
distributed under the License is distributed on an "AS IS" BASIS,
WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
See the License for the specific language governing permissions and
limitations under the License.