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]>

Manual readme review

Author: evan-masseau

README.md

@@ -103,29 +103,9 @@ yarn add klaviyo-react-native-sdk
 
 ### Example App
 
-We have included an example app in this repository for reference of how to integrate with our SDK.
-It is primarily intended to give code samples such as how and where to `initialize`, implement notification
-delegate methods on iOS, and handle an opened notification intent on Android. We've commented the sample app
-code to call out key setup steps, search for `iOS Installation Step` and `Android Installation Step`.
-
-To run the example app:
-
-- Clone this repository
-- From the root directory, run `yarn example setup`. This is an alias that will do the following:
-  - 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.
-  - `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
+The [example app](./example) is a reference integration demonstrating SDK setup and
+exercising the public API surface. See [`example/README.md`](./example/README.md) for
+setup instructions, Firebase configuration, and a walkthrough of the demonstrated features.
 
 ### Android
 

example/README.md

@@ -0,0 +1,143 @@
+# Klaviyo React Native SDK Example App
+
+The example app is a reference integration of the Klaviyo React Native SDK. It demonstrates
+a basic Klaviyo integration with all major SDK features including:
+
+- Initialization
+- Analytics
+- Push Notifications
+- Geofencing
+- Deep Linking
+- In-App Forms
+
+## Integration Step Comments
+
+The example source is annotated with `RN|iOS|Android Installation Step` comments that mark
+the code an integrator needs to replicate in their own app. Grep for any of those prefixes  
+across `example/` to walk the integration surface:
+
+- `RN Installation Step` — `example/src/App.tsx` and `example/index.js` (SDK init,
+  API key sourcing, optional `@react-native-firebase/messaging` background handler)
+- `iOS Installation Step` — `example/ios/KlaviyoReactNativeSdkExample/AppDelegate.{h,mm}`,
+  `PushNotificationsHelper.swift`, `NotificationService.swift`, and the Podfile
+- `Android Installation Step` — `example/android/build.gradle`, `app/build.gradle`,
+  `AndroidManifest.xml`, and `MainActivity.kt`
+
+## 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 (`.env` is gitignored)
+3. Restart Metro with `yarn start --reset-cache` so the metro 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/`).
+
+### 2. Install Dependencies
+
+The one-liner, run from the repo root:
+
+```bash
+# From the repo root
+yarn example setup
+
+# This alias runs:
+#   yarn install --immutable           (repo root)
+#   bundle install                     (example/)
+#   bundle exec pod install            (example/ios/)
+```
+
+### 3. Run the App
+
+Preferred — from the repo root (yarn workspaces entry point):
+
+```bash
+# From the repo root
+yarn example start
+yarn example android
+yarn example ios
+```
+
+## Push Notifications
+
+Push notifications are handled via `@react-native-firebase/messaging` in the
+JavaScript layer — the Klaviyo SDK is initialized from JS, and Firebase manages
+push tokens cross-platform.
+
+### Platform-specific Firebase setup
+
+**Android** builds and runs out of the box without Firebase configured. The
+`com.google.gms.google-services` plugin is conditionally applied only when
+`google-services.json` is present. Without the file, push features are dormant
+but everything else (profile, events, in-app forms, geofencing) works normally.
+
+- To enable push: drop a real `google-services.json` from your Firebase project
+  into `example/android/app/`. The file is gitignored. Ensure the
+  `applicationId` in `example/android/app/build.gradle`
+  (`com.klaviyoreactnativesdkexample`) is registered as an Android app in your
+  Firebase project.
+
+**iOS** requires a `GoogleService-Info.plist` at `example/ios/` to build at all — the Xcode
+project's Resources build phase references it unconditionally. Two options:
+
+- **To enable push:** drop a real `GoogleService-Info.plist` from your Firebase
+  project at `example/ios/GoogleService-Info.plist` (gitignored). Ensure your
+  iOS bundle identifier is registered in the same Firebase project.
+- **To build without push:** write a stub plist at the same path. The values
+  below are format-valid (39-char `API_KEY` starting with `A`, full
+  `GOOGLE_APP_ID` format), so `FirebaseApp.configure()` succeeds at launch.
+  Firebase will log a benign "couldn't register with backend" warning at
+  runtime since the project isn't real — that's expected, not a bug. The rest
+  of the app works normally.
+  <details>
+  <summary>Stub <code>GoogleService-Info.plist</code></summary>
+
+  ```xml
+  <?xml version="1.0" encoding="UTF-8"?>
+  <!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
+  <plist version="1.0">
+  <dict>
+    <key>BUNDLE_ID</key><string>com.klaviyoreactnativesdkexample</string>
+    <key>GOOGLE_APP_ID</key><string>1:000000000000:ios:0000000000000000000000</string>
+    <key>API_KEY</key><string>AIzaSyA00000000000000000000000000000000</string>
+    <key>GCM_SENDER_ID</key><string>000000000000</string>
+    <key>PROJECT_ID</key><string>stub-project</string>
+    <key>STORAGE_BUCKET</key><string>stub-project.appspot.com</string>
+    <key>PLIST_VERSION</key><string>1</string>
+    <key>IS_GCM_ENABLED</key><true/>
+    <key>IS_ADS_ENABLED</key><false/>
+    <key>IS_ANALYTICS_ENABLED</key><false/>
+    <key>IS_APPINVITE_ENABLED</key><false/>
+    <key>IS_SIGNIN_ENABLED</key><false/>
+  </dict>
+  </plist>
+  ```
+
+  </details>
+
+### Native push (alternative)
+
+For apps that prefer to handle push tokens natively (e.g., brownfield apps), the
+Klaviyo iOS and Android SDKs both have their own native push APIs. See the
+`AppDelegate.mm` comments on iOS and `MainApplication.kt` comments on Android for
+pointers, plus the platform SDKs' READMEs:
+
+- iOS: https://github.com/klaviyo/klaviyo-swift-sdk#push-notifications
+- Android: https://github.com/klaviyo/klaviyo-android-sdk#push-notifications
+
+Note: both platforms require native-layer push-open handling regardless of how tokens
+are managed:
+
+- **Android:** `Klaviyo.handlePush(intent)` in `MainActivity.kt` (`onCreate` +
+  `onNewIntent`) — covers cold-start taps and resume-from-background taps.
+- **iOS:** `[PushNotificationsHelper handleReceivingPushWithResponse:...]` inside
+  the `userNotificationCenter:didReceiveNotificationResponse:withCompletionHandler:`
+  delegate in `AppDelegate.mm`, plus the `getLaunchOptionsWithURL` helper to
+  forward any cold-start deep-link URL (React Native issue
+  [#32350](https://github.com/facebook/react-native/issues/32350)).

example/android/app/build.gradle

@@ -114,7 +114,7 @@ dependencies {
     // The version of react-native is set by the React Native Gradle Plugin
     implementation("com.facebook.react:react-android")
 
-    // Android Installation Step 1b - add firebase dependency if using push
+    // Android Installation Step - add firebase dependency if using push
     implementation 'com.google.firebase:firebase-messaging-ktx:24.0.0'
 
     if (hermesEnabled.toBoolean()) {
@@ -124,11 +124,14 @@ dependencies {
     }
 }
 
-// Apply the google-services plugin only when google-services.json is present.
-// This lets the example app build out of the box without a Firebase project.
-// To enable push: drop your Firebase project's google-services.json into
-// example/android/app/, and make sure its package_name matches applicationId
-// above. See example/README.md for full setup details.
+// For the example app we only apply the google-services plugin
+// when google-services.json is present. This lets the example app build out of
+// the box without a Firebase project. To enable push: drop your Firebase
+// project's google-services.json into example/android/app/, and make sure its
+// package_name matches applicationId above. See example/README.md for full
+// setup details. The equivalent on iOS is the `#if __has_include(...)` +
+// `if (plistPath)` guard in example/ios/.../AppDelegate.mm.
 if (file('google-services.json').exists()) {
+    // Optional Android Installation Step: Apply the google-services plugin to enable push
     apply plugin: "com.google.gms.google-services"
 }

example/android/app/src/main/AndroidManifest.xml

@@ -1,4 +1,3 @@
-<!-- Android Installation Step 2: Configure manifest.xml ... -->
 <manifest xmlns:android="http://schemas.android.com/apk/res/android">
 
     <uses-permission android:name="android.permission.INTERNET" />
@@ -23,18 +22,18 @@
             <category android:name="android.intent.category.LAUNCHER" />
         </intent-filter>
 
-        <!-- Android Installation Step 2a: Configure deep links, if your push notifications will contain them -->
+        <!-- Android Installation Step: Configure deep links, if your push notifications will contain them -->
         <intent-filter android:label="deep_link_filter">
           <action android:name="android.intent.action.VIEW"/>
 
           <category android:name="android.intent.category.DEFAULT"/>
           <category android:name="android.intent.category.BROWSABLE"/>
 
-          <!-- Accepts URIs that begin with "klaviyosample://” -->
-          <data android:scheme="klaviyosample"/>
+          <!-- Accepts URIs that begin with "klaviyotest://” -->
+          <data android:scheme="klaviyotest"/>
         </intent-filter>
 
-        <!-- Android Installation Step 2b: Configure verified app links for Universal Link Click Tracking -->
+        <!-- Android Installation Step: Configure verified app links for Universal Link Click Tracking -->
         <intent-filter android:label="app_link_handler" android:autoVerify="true">
           <action android:name="android.intent.action.VIEW" />
           <category android:name="android.intent.category.DEFAULT" />
@@ -46,7 +45,7 @@
 
       </activity>
 
-      <!-- Android Installation Step 2b: Register KlaviyoPushService to receive MESSAGING_EVENT intents. -->
+      <!-- Android Installation Step: Register KlaviyoPushService to receive MESSAGING_EVENT intents. -->
       <service
           android:name="com.klaviyo.pushFcm.KlaviyoPushService"
           android:exported="false">
@@ -55,14 +54,14 @@
           </intent-filter>
       </service>
 
-      <!-- Optional Android Installation Step 2c: Specify an icon for Klaviyo notifications  -->
+      <!-- Optional Android Installation Step: Specify an icon for Klaviyo notifications  -->
       <!-- Absent this key, Klaviyo SDK will look for com.google.firebase.messaging.default_notification_icon -->
       <!-- and absent that, use the default launcher icon for your app -->
       <meta-data
           android:name="com.klaviyo.push.default_notification_icon"
           android:resource="@drawable/ic_notification" />
 
-      <!-- Optional Android Installation Step 2d: Specify a notification color for Klaviyo notifications  -->
+      <!-- Optional Android Installation Step: Specify a notification color for Klaviyo notifications  -->
       <!-- Absent this key, Klaviyo SDK will look for com.google.firebase.messaging.default_notification_color -->
       <!-- and absent that, omit specifying a color -->
       <meta-data android:name="com.klaviyo.push.default_notification_color"

example/android/app/src/main/java/com/klaviyoreactnativesdkexample/MainActivity.kt

@@ -27,7 +27,7 @@ class MainActivity : ReactActivity() {
     Log.v("KlaviyoSampleApp", "MainActivity.onCreate()")
     super.onCreate(savedInstanceState)
 
-    // Android Installation Step 5a: Depending on the state of your application when the notification is tapped,
+    // Android Installation Step: Depending on the state of your application when the notification is tapped,
     // the intent have started this activity, or it might be received via onNewIntent if the app was already running.
     // We recommend passing all intents through Klaviyo.handlePush to make sure you don't miss a use case.
     onNewIntent(intent)
@@ -38,7 +38,7 @@ class MainActivity : ReactActivity() {
     Log.v("KlaviyoSampleApp", "Launch Intent: " + intent.toString())
     super.onNewIntent(intent)
 
-    // Android Installation Step 5: Call handlePush when a push notification is tapped
+    // Android Installation Step: Call handlePush when a push notification is tapped
     // Note: due to platform differences, this step must be implemented in native code.
     // Tapping on a notification broadcasts an intent to your app. This method detects if the
     // intent originated from a Klaviyo push notification and registers a special Opened Push event

example/android/build.gradle

@@ -1,6 +1,5 @@
 buildscript {
     ext {
-        // Android Installation Step 1a: Set compatible minSdkVersion and compileSdkVersion
         minSdkVersion = 24
         targetSdkVersion = 36 // Typically minSdkVersion <= targetSdkVersion <= compileSdkVersion
         compileSdkVersion = 36
@@ -17,7 +16,8 @@ buildscript {
         classpath("com.facebook.react:react-native-gradle-plugin")
         classpath("org.jetbrains.kotlin:kotlin-gradle-plugin")
 
-        // Android Installation Step - Required dependency to initialize firebase via google-services.json file
+        // Android Installation Step: google-services Gradle plugin,
+        // required to process google-services.json if you're enabling push.
         classpath("com.google.gms:google-services:4.4.2")
     }
 }

example/ios/KlaviyoReactNativeSdkExample/AppDelegate.h

@@ -8,7 +8,6 @@
 #import "klaviyo_react_native_sdk-Swift.h"
 #endif
 
-// iOS Installation Step 1: Conform AppDelegate to UNUserNotificationCenterDelegate
 @interface AppDelegate: RCTAppDelegate <UNUserNotificationCenterDelegate>
 
 @end