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

@@ -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,168 @@
+# Klaviyo React Native SDK Example App
+
+The example app is a reference integration of the Klaviyo React Native SDK. It
+demonstrates where and how to `initialize`, implement notification delegate
+methods on iOS, handle opened notification intents on Android, and exercise the
+SDK's public API surface (profile, events, in-app forms, geofencing, push).
+Sample code is annotated — search for `JS Installation Step`, `iOS Installation Step`,
+and `Android Installation Step` in the source to find the integration callouts.
+
+## 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.
+- If `KLAVIYO_API_KEY` is missing or still set to the placeholder, the app fails
+  fast at module load with a clear error — no silent misbehavior. Copy
+  `.env.template` to `.env` and set a real key before running.
+
+### 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/)
+```
+
+You can run those steps manually if you prefer, but `yarn example setup` is the
+preferred entry point.
+
+### 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
+```
+
+Alternatively, from the `example/` directory:
+
+```bash
+# Start Metro bundler
+yarn start
+
+# Run iOS
+yarn ios
+
+# Run Android
+yarn android
+```
+
+## 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. Then run
+  `bundle exec pod install` from `example/ios/`.
+- **To build without push:** write a stub plist at the same path. The app's
+  AppDelegate guards `[FIRApp configure]` on the real plist's presence of valid
+  values — a stub passes the Xcode build-input check, Firebase logs an
+  invalid-config warning at runtime, and the rest of the app works. Stub
+  content you can copy:
+  <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:0000000000000000</string>
+    <key>API_KEY</key><string>stub-for-ci</string>
+    <key>GCM_SENDER_ID</key><string>000000000000</string>
+    <key>PROJECT_ID</key><string>stub-project</string>
+    <key>STORAGE_BUCKET</key><string>stub.appspot.com</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: `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.
+
+## Integration Step Comments
+
+The example source is annotated with `JS Installation Step`, `iOS Installation Step`,
+and `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:
+
+- `JS 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`
+
+Each comment is self-describing — the prefix is just a grep handle, not part of a
+strictly ordered checklist. Some steps are labelled by concern rather than being
+numbered (e.g., "Firebase, part 1 of 2") where that reads more clearly than an
+ordinal would.
+
+## 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

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,13 @@ 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.
+// Optional Android Installation Step: 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. The equivalent on iOS is the `#if __has_include(...)` +
+// `if (plistPath)` guard in example/ios/.../AppDelegate.mm.
 if (file('google-services.json').exists()) {
     apply plugin: "com.google.gms.google-services"
 }

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

@@ -1,4 +1,4 @@
-<!-- Android Installation Step 2: Configure manifest.xml ... -->
+<!-- Android Installation Step: Configure manifest.xml ... -->
 <manifest xmlns:android="http://schemas.android.com/apk/res/android">
 
     <uses-permission android:name="android.permission.INTERNET" />
@@ -23,7 +23,7 @@
             <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"/>
 
@@ -34,7 +34,7 @@
           <data android:scheme="klaviyosample"/>
         </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 +46,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 +55,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,13 +38,13 @@ 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
     Klaviyo.handlePush(intent)
 
-    // Android Installation Step 6: Deep linking from native layer (uncommon)
+    // Android Installation Step: Deep linking from native layer (uncommon)
     // Read deep link data from intent, open the appropriate page
     val action: String? = intent?.action // e.g. ACTION_VIEW
     val deepLink: Uri? = intent?.data // e.g. klaviyoreactnativesdkexample://link

example/android/build.gradle

@@ -1,6 +1,6 @@
 buildscript {
     ext {
-        // Android Installation Step 1a: Set compatible minSdkVersion and compileSdkVersion
+        // Android Installation Step: Set compatible minSdkVersion and compileSdkVersion
         minSdkVersion = 24
         targetSdkVersion = 36 // Typically minSdkVersion <= targetSdkVersion <= compileSdkVersion
         compileSdkVersion = 36
@@ -17,7 +17,10 @@ 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
+        // Optional Android Installation Step: google-services Gradle plugin,
+        // required to process google-services.json if you're enabling push.
+        // The plugin is applied conditionally in app/build.gradle; see the
+        // `apply plugin: "com.google.gms.google-services"` guard there.
         classpath("com.google.gms:google-services:4.4.2")
     }
 }

example/index.js

@@ -2,9 +2,10 @@ import { AppRegistry } from 'react-native';
 import App from './src/App';
 import { name as appName } from './app.json';
 
-// @react-native-firebase/messaging requires a background message handler to be
-// registered at module load — before AppRegistry.registerComponent — or it will
-// warn on every cold start ("No task registered for key ReactNativeFirebaseMessagingHeadlessTask").
+// JS Installation Step (only if using @react-native-firebase/messaging):
+// Register a background message handler at module load — before
+// AppRegistry.registerComponent — or RNFB will warn on every cold start
+// ("No task registered for key ReactNativeFirebaseMessagingHeadlessTask").
 // See https://rnfirebase.io/reference/messaging#setBackgroundMessageHandler
 //
 // For Klaviyo push, this is a no-op: Klaviyo delivers notifications through

example/ios/KlaviyoReactNativeSdkExample/AppDelegate.h

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