Add Firebase FAQ

docs/guides/component-examples/firebase-database-migration.md

@@ -74,19 +74,58 @@ A safe, incremental approach:
 1. **Add the new component to a single screen first.** Keep the old component on every other screen so the rest of the app keeps working while you experiment.
 2. **Re-create the blocks** on that screen using the new component. The block names are the same, so this is mostly drag-and-drop.
 3. **Map the old `Project Bucket`** value to the new `Project Path` property, and remove `Firebase URL` / `Firebase Token` references — those properties don't exist on the new component.
-4. **Test on a device.** Confirm reads, writes, and `Data Changed` events all work as expected.
+4. **Test by building an APK and installing it on a device.** The Companion cannot fully exercise **Firebase Realtime Database** — see the warning below — so live-testing via the Companion will not give you a reliable signal. Build an APK, install it, and confirm reads, writes, and `Data Changed` events all work as expected.
 5. **Repeat for the remaining screens.** When all screens are migrated, you can delete the old **Firebase Database** component from your project.
 
-!!! tip "Live-test both components side by side via the Companion"
-    During the migration you can drop both **Firebase Database** and **Firebase Realtime Database** onto the same screen and exercise them via the Companion. The Companion live-testing path runs both happily — only the APK/AAB build is blocked while the deprecated component is still present.
+!!! warning "Don't test the new component via the Companion"
+    **Firebase Realtime Database** initialises from your project's `google-services.json` and the package name and SHA-1 signature registered in your Firebase project. The Companion runs under its own package name and signature and does not bundle your `google-services.json`, so the SDK cannot authenticate against your Firebase project from there. Reads and writes will fail with errors like `Can not call 'Get Value' if the firebase object is NULL`. Always test the new component on a built APK installed on a real device.
 
 !!! warning "APK build with `Firebase Realtime Database` requires `google-services.json`"
     As soon as **Firebase Realtime Database** is in the project, the build server requires a `google-services.json` asset. If it's missing, the build fails with `google-services.json file not found in assets directory`. Upload it before building.
 
 ## Rolling back
 
-If you hit a problem with the new component during migration, you can revert the affected screen to use the old component again — but remember that as long as **Firebase Database** is still in the project, you will not be able to build an APK or AAB. Use the Companion for live testing while you sort it out, then complete the migration before shipping.
+If you hit a problem with the new component during migration, you can revert the affected screen to use the old component again — but remember that as long as **Firebase Database** is still in the project, you will not be able to build an APK or AAB. Build APKs (not Companion sessions) to validate behaviour while you sort it out, then complete the migration before shipping.
 
 ## When to remove the old component
 
 The old **Firebase Database** component is deprecated. It still loads in the Designer and runs in the Companion so you can migrate without losing block context, but **APK and AAB builds will fail while it is present**. Remove it from your project as soon as every screen has been migrated.
+
+## FAQ
+
+### `FirebaseError: Can not call 'Get Value' if the firebase object is NULL`
+
+The new component could not initialise, so every block call hits a null SDK instance. In order of likelihood, the cause is one of:
+
+1. **You're testing through the Companion.** The Companion does not run under your project's package name or signature and does not load your `google-services.json`, so the new component cannot connect to your Firebase project from there. Build an APK and test on a device instead.
+2. **`google-services.json` is missing or incomplete.** Re-download it from **Firebase Console → Project settings → Your apps → Android app** and upload it via the Designer's **Media** section. Open the file in a text editor and confirm it contains a `firebase_url` entry under `project_info` — if it doesn't, your Firebase project doesn't have Realtime Database enabled yet, so enable it in the Firebase Console and download a fresh copy.
+3. **Package name mismatch.** The `package_name` inside `google-services.json` must exactly match the package name configured in **Project Properties → Package Name**. If you changed the package name after registering the Android app in Firebase, register a new app under the new name and download the new `google-services.json`.
+4. **SHA-1 signature mismatch.** If your database rules or Firebase Authentication require a registered SHA-1, the certificate Kodular signs your APK with must be added to the Android app in the Firebase Console under **Project settings → Your apps → SHA certificate fingerprints**. Use the SHA-1 of your keystore (or the Kodular default debug keystore for unsigned test builds).
+
+### Where did the `Firebase URL` and `Firebase Token` properties go?
+
+Both were removed on purpose. The database URL is now read from `google-services.json` at build time, so there is no field to fill in. Authentication is delegated to the **Firebase Authentication** component — sign the user in there and **Firebase Realtime Database** automatically uses that identity. See [Authentication](#authentication) above.
+
+### My old app crashes with `NullPointerException` in `WebSocketHandshake.verifyServerHandshakeHeaders`
+
+This is a known crash inside the legacy SDK that ships with the deprecated **Firebase Database** component. It is triggered when the WebSocket handshake response contains a header the old SDK cannot parse, and there is no fix on the old component — the SDK has been unmaintained by Google for years. Migrating to **Firebase Realtime Database** resolves it because the new component uses a current SDK that does not have this bug.
+
+### Build fails with `google-services.json file not found in assets directory`
+
+As soon as **Firebase Realtime Database** is in the project, the build server requires a `google-services.json` asset. Upload it from the Designer's **Media** section and rebuild.
+
+### Reads and writes return nothing (or get permission-denied) on a built APK
+
+Your security rules likely still expect custom claims minted by the old component's token-based auth. The new component authenticates as a normal Firebase user, so rules need to check `auth.uid` (or `auth != null`) instead. Update the rules in the Firebase Console — see the [Firebase Rules guide](firebase-rules.md) for examples.
+
+### Why can't I test the new component in the Companion?
+
+The Companion is a separate APK that ships with its own package name and its own signing certificate, and it does not load your project's `google-services.json` at runtime. **Firebase Realtime Database** authenticates against your Firebase project using exactly those three things — package name, signature, and `google-services.json` — so from inside the Companion the SDK has nothing valid to connect with. This is a hard limitation of how Firebase verifies clients, not a Kodular bug. Build an APK and install it on a real device to test.
+
+### Can I keep both `Firebase Database` and `Firebase Realtime Database` on the same screen during migration?
+
+In the Designer, yes — that's how you re-create blocks side by side. At runtime, the new component will not work in the Companion (see above) and APK/AAB builds are blocked entirely while the deprecated component is present. The practical migration path is: rebuild the blocks alongside the old ones in the Designer, delete the old component, then build an APK to test the new one.
+
+### How do I map `Project Bucket` to `Project Path`?
+
+Use the same string. If the old component had `Developer Bucket = "myapp"` and `Project Bucket = "users"`, set `Project Path = "users"` on the new component. The `Developer Bucket` concept does not exist on the new component — every project has its own database, so there is no shared bucket to namespace under.