Merge branch 'feat/geofencing' into rel/2.2.0-alpha.1

Author: belleklaviyo

README.md

@@ -40,6 +40,11 @@
     - [Setup](#setup-1)
       - [In-App Forms Session Configuration](#in-app-forms-session-configuration)
     - [Unregistering from In-App Forms](#unregistering-from-in-app-forms)
+
+  - [Geofencing](#geofencing)
+    - [Prerequisites](#prerequisites-2)
+    - [Setup](#setup-2)
+    - [Unregistering from Geofencing](#unregistering-from-geofencing)
   - [Troubleshooting](#troubleshooting)
   - [Contributing](#contributing)
   - [License](#license)
@@ -591,6 +596,49 @@ Klaviyo.unregisterFromInAppForms(config);
 
 Note that after unregistering, the next call to `registerForInAppForms()` will be considered a new session by the SDK.
 
+## Geofencing
+
+> ℹ️ Support for Geofencing is currently available for early access to select Klaviyo customers. Please contact your CSM to be enrolled.
+
+> Alpha geofencing support is available in SDK version 2.2.0-alpha.1 and higher.
+
+Geofencing allows you to trigger events when users enter or exit geographic regions. The Klaviyo SDK monitors geofences configured in your Klaviyo account and automatically tracks geofence enter and exit events. The SDK automatically handles geofence synchronization with your Klaviyo account—when you add, update, or remove geofences in Klaviyo, the SDK will automatically sync these changes on the next app launch or when the API key changes.
+
+### Prerequisites
+
+Integrating geofencing is highly platform-specific as it utilizes the native monitoring systems. Begin by thoroughly reviewing the setup
+instructions for Geofencing in the README from each native Klaviyo SDK:
+
+- [Android](https://github.com/klaviyo/klaviyo-android-sdk/tree/rel/4.2.0-rc.1?tab=readme-ov-file#geofencing)
+- [iOS](https://github.com/klaviyo/klaviyo-swift-sdk/tree/rel/5.2.0-alpha.1?tab=readme-ov-file#geofencing)
+
+### Setup
+
+To enable geofencing in your app, you must:
+
+1. Configure location permissions in your app's platform-specific configuration files
+2. Call `Klaviyo.registerGeofencing()` after initializing the SDK
+
+4. Register for geofencing after initializing the SDK:
+   ```typescript
+   import { Klaviyo } from 'klaviyo-react-native-sdk';
+   
+   // After initializing with your public API key
+   Klaviyo.registerGeofencing();
+   ```
+
+### Unregistering from Geofencing
+
+If at any point you need to stop monitoring geofences, e.g. when the user logs out or opts out of location tracking, you may call:
+
+```typescript
+import { Klaviyo } from 'klaviyo-react-native-sdk';
+
+Klaviyo.unregisterGeofencing();
+```
+
+After unregistering, the SDK will stop monitoring geofences and will no longer report geofence transition events. You can call `registerGeofencing()` again to resume monitoring.
+
 ## Troubleshooting
 
 Use the [troubleshooting guide](Troubleshooting.md) to resolve common issues with the Klaviyo React Native SDK.

Troubleshooting.md

@@ -110,3 +110,8 @@ Make sure to use the URL scheme (rntest://) of the example app when testing.
 There is an open issue with [`@react-native-firebase/messaging`](https://github.com/invertase/react-native-firebase/issues/8022) where the SDK will uppercase any APNS token returned using `messaging().getAPNSToken()`.
 You can verify this by adding a log the `AppDelegate.m` file that prints the deviceToken (you will need to convert to a hex string).
 This might have no impact on your use case, but is something to consider when designing.
+
+### iOS Geofencing Events not Firing
+
+The delivery of geofence events to the Klaviyo SDK requires registering for geofences in the native iOS layer in `didFinishLaunchingWithOptions`. If you only call `Klaviyo.registerGeofencing()` in the React Native layer or any later in the lifecycle, triggered enter/exit events may not get delivered in a reliable manner as the native monitoring service relies on that AppDelegate entry point.
+

example/ios/KlaviyoReactNativeSdkExample/AppDelegate.mm

@@ -35,7 +35,7 @@ - (BOOL)application:(UIApplication *)application
 
   // Start monitoring geofences from background
   dispatch_async(dispatch_get_main_queue(), ^{
-    [KlaviyoBridge monitorGeofencesFromBackground];
+    [KlaviyoBridge registerGeofencing];
   });
 
   // refer to installation step 16 below

example/ios/KlaviyoReactNativeSdkExample/Info.plist

@@ -50,16 +50,13 @@
 	</dict>
 	<key>NSLocationAlwaysAndWhenInUseUsageDescription</key>
 	<string>We need access to your location at all times to provide geofencing features, including when the app is in the background.</string>
-	<key>NSLocationAlwaysUsageDescription</key>
-	<string>We need access to your location at all times to provide geofencing features, including when the app is in the background.</string>
 	<key>NSLocationWhenInUseUsageDescription</key>
 	<string>We use your location to provide location-based features and geofencing.</string>
 	<key>RCTNewArchEnabled</key>
 	<true/>
 	<key>UIBackgroundModes</key>
 	<array>
 		<string>location</string>
-		<string>fetch</string>
 	</array>
 	<key>UILaunchStoryboardName</key>
 	<string>LaunchScreen</string>

ios/KlaviyoBridge.swift

@@ -69,23 +69,13 @@ public class KlaviyoBridge: NSObject {
     @MainActor
     @objc
     public static func registerGeofencing() {
-        Task { @MainActor in
-            await KlaviyoSDK().registerGeofencing()
-        }
-    }
-
-    @MainActor
-    @objc
-    public static func monitorGeofencesFromBackground() {
-        KlaviyoSDK().monitorGeofencesFromBackground()
+        KlaviyoSDK().registerGeofencing()
     }
 
     @MainActor
     @objc
     public static func unregisterGeofencing() {
-        Task { @MainActor in
-            await KlaviyoSDK().unregisterGeofencing()
-        }
+        KlaviyoSDK().unregisterGeofencing()
     }
 
     @MainActor