docs(example): update READMEs for JS-first init and Firebase push setup

Root README: rewrite the example-app section to reflect the JS-first
initialization flow (API key via .env, Firebase push optional) instead of
the removed initializeKlaviyoFromNative toggle.

example/README.md: new standalone setup guide covering .env configuration,
iOS Firebase setup (GoogleService-Info.plist + pod install), Android
Firebase setup (google-services.json vs the shipped .template), and the
push-disabled path (app runs cleanly without Firebase configured).

Co-Authored-By: Claude Opus 4.7 (1M context) <[email protected]>

Author: evan-masseau

README.md

@@ -115,14 +115,22 @@ To run the example app:
   - Run `yarn install --immutable` from the root directory
   - Navigate to the `example` directory and run `bundle install`
   - Navigate to the `example/ios` directory and run `bundle exec pod install`
-- Android configuration:
-  - To initialize Klaviyo from the native layer, open `example/android/gradle.properties` and follow the
-    instructions to set your `publicApiKey` and verify `initializeKlaviyoFromNative` is enabled.
-  - If you wish to run the Android example app with push/firebase, you'll need to copy a `google-services.json`
-    file into `example/android/app/src` and update the `applicationId` in `app/build.gradle` to match your application ID.
-    Then, open `example/android/gradle.properties` and follow the instructions to enable `useNativeFirebase`.
-    This is disabled by default because the app will crash on launch without a `google-services.json` file.
-- From the project's root directory, use the following commands start a metro server and run the example app.
+- Configure your public API key:
+  - The example app initializes the SDK from JavaScript/TypeScript via an `.env` file
+    (loaded with [`react-native-dotenv`](https://github.com/goatandsheep/react-native-dotenv)).
+    Copy `example/.env.template` to `example/.env` and set your `KLAVIYO_API_KEY`.
+    `.env` is gitignored. If you skip this step the app still runs and shows a friendly
+    warning banner — non-push features work without an API key.
+    If Metro was already running when you set up `.env`, restart it with
+    `yarn start --reset-cache` so `react-native-dotenv` picks up the new value.
+    See [`example/README.md`](./example/README.md) for the full walkthrough.
+  - If you prefer to initialize natively instead, commented reference implementations live in
+    [`MainApplication.kt`](./example/android/app/src/main/java/com/klaviyoreactnativesdkexample/MainApplication.kt)
+    and [`AppDelegate.mm`](./example/ios/KlaviyoReactNativeSdkExample/AppDelegate.mm).
+- Push notifications are disabled by default. To enable them, add your Firebase config files as described
+  in [`example/README.md`](./example/README.md#firebase-setup). Without those files the app runs fine —
+  the push section is simply disabled and the rest of the demo works as usual.
+- From the project's root directory, use the following commands to start a metro server and run the example app.
   - `yarn example start` - to start the metro server
   - `yarn example android` - to run the example app on an Android emulator or device
   - `yarn example ios` - to run the example app on an iOS simulator

example/README.md

@@ -0,0 +1,95 @@
+# Klaviyo React Native SDK Example App
+
+This example app demonstrates the full API surface of the Klaviyo React Native SDK, including profile management, event tracking, in-app forms, geofencing, and push notifications.
+
+## Getting Started
+
+### 1. Configure Your API Key
+
+The app loads your Klaviyo public API key from a gitignored `.env` file via
+[`react-native-dotenv`](https://github.com/goatandsheep/react-native-dotenv).
+
+1. Copy the template: `cp .env.template .env`
+2. Edit `.env` and set `KLAVIYO_API_KEY=` to your actual public API key
+3. Restart Metro with `yarn start --reset-cache` so the babel plugin picks up the new value
+
+> **If you hit "Klaviyo API key not configured" after setting up `.env`:** Metro inlines
+> `.env` values at bundle time via `react-native-dotenv`. If Metro was already running when
+> you created or edited `.env`, it will serve a cached bundle with `KLAVIYO_API_KEY` still
+> undefined. Stop Metro and restart it with `yarn start --reset-cache` (from `example/`).
+
+Notes:
+
+- `.env` is gitignored — only `.env.template` is checked in.
+- Without a `.env` file the app still builds and runs; it shows a friendly warning
+  banner and the non-push features (profile, events, in-app forms, geofencing)
+  continue to work without a key.
+
+### 2. Install Dependencies
+
+```bash
+yarn install
+cd ios && pod install && cd ..
+```
+
+### 3. Run the App
+
+```bash
+# Start Metro bundler
+yarn start
+
+# Run iOS
+yarn ios
+
+# Run Android
+yarn android
+```
+
+## Push Notifications
+
+**Push is disabled by default.** The example app launches without any Firebase
+configuration — the rest of the demo (profile management, events, in-app forms,
+geofencing) still works, and the Push Notifications section just shows setup
+instructions until you wire Firebase up.
+
+Push notifications are handled via `@react-native-firebase/messaging` in the
+JavaScript layer. This is the recommended approach for React Native apps — the
+SDK is initialized from JS, and Firebase manages push tokens cross-platform.
+
+### Firebase Setup
+
+To enable push notifications, add your Firebase configuration files:
+
+**iOS:**
+
+1. Add `GoogleService-Info.plist` to `example/ios/KlaviyoReactNativeSdkExample/`
+2. Run `pod install` from the `example/ios/` directory
+
+**Android:**
+
+1. Replace `example/android/app/google-services.json.template` with a real
+   `google-services.json` from your Firebase project.
+   - The template is a placeholder structure checked into the repo so that the
+     Android build succeeds without real Firebase config. It lets the app run
+     (with push simply disabled) on a cold clone. Replace it with a real
+     `google-services.json` to enable push on Android.
+   - `google-services.json` itself is gitignored — only the template is checked in.
+2. Ensure `applicationId` in `build.gradle` matches your Firebase project.
+
+The app automatically detects Firebase and enables push features once the config
+files are in place.
+
+### Native Push (Alternative)
+
+For apps that prefer to handle push tokens natively (e.g., brownfield apps), the native code in `AppDelegate.mm` and `MainApplication.kt` contains commented-out reference implementations. See those files for details.
+
+Note: `Klaviyo.handlePush(intent)` in `MainActivity.kt` is always required on Android — push open tracking depends on native intent handling regardless of how tokens are managed.
+
+## Features Demonstrated
+
+- **Profile Management** — Set email, phone, external ID individually or together; reset profile
+- **Event Tracking** — Create test events and Viewed Product events
+- **In-App Forms** — Register/unregister with configurable session timeout
+- **Geofencing** — Location permission flow, register/unregister, list current geofences
+- **Push Notifications** — Firebase-based permission request, token display, badge count (iOS)
+- **Deep Linking** — Universal tracking link handling via `Linking` API