zixflow-reactnative 1.1.3 → 1.1.5

package/README.md

@@ -33,25 +33,17 @@ Welcome to the **Zixflow React Native SDK** integration guide. This comprehensiv
    - [Requesting Permission](#requesting-permission)
    - [Handling Push Notifications](#handling-push-notifications)
    - [Device Token Registration](#device-token-registration)
-9. [In-App Messaging](#in-app-messaging)
-   - [Event Listeners](#event-listeners)
-   - [Message Events](#message-events)
-   - [Dismissing Messages](#dismissing-messages)
+9. [Push Notification Tracking](#push-notification-tracking)
 10. [Location Tracking](#location-tracking)
-11. [Advanced Configuration](#advanced-configuration)
-    - [Region Settings](#region-settings)
+11. [Geofence Tracking](#geofence-tracking)
+12. [Live Activities](#-live-activities)
+13. [Notification Inbox](#notification-inbox)
+14. [Advanced Configuration](#advanced-configuration)
     - [Log Levels](#log-levels)
     - [Auto-Tracking Options](#auto-tracking-options)
     - [Custom API Hosts](#custom-api-hosts)
-12. [Troubleshooting](#troubleshooting)
-    - [Installation Issues](#installation-issues)
-    - [iOS Build Errors](#ios-build-errors)
-    - [Android Build Errors](#android-build-errors)
-    - [Push Notification Issues](#push-notification-issues)
-    - [In-App Message Issues](#in-app-message-issues)
-13. [Example Applications](#example-applications)
-14. [API Reference](#api-reference)
-15. [Support & Resources](#support--resources)
+15. [Example Applications](#example-applications)
+16. [API Reference](#api-reference)
 
 ---
 
@@ -98,6 +90,10 @@ The SDK is built on top of the native Zixflow iOS and Android SDKs, providing a
 
 ## Installation
 
+The Zixflow React Native SDK is available on **npm**. You can browse the package here:
+
+ **[npm - zixflow-reactnative](https://www.npmjs.com/package/zixflow-reactnative)**
+
 ### npm Installation
 
 Install the SDK using npm:
@@ -199,7 +195,6 @@ target 'NotificationServiceExtension' do
   pod "ZixflowMessagingPush", "~> 1.0"
   pod "ZixflowDataPipelines", "~> 1.0"
   pod "ZixflowCommon", "~> 1.0"
-  pod "ZixflowTrackingMigration", "~> 1.0"
   pod "AnalyticsSwiftZixflow", "1.7.3+zixflow.1"
 end
 ```
@@ -533,6 +528,8 @@ const handleLogout = async () => {
 
 Complete guide to implementing push notifications in React Native with Zixflow using Apple Push Notifications (APNs) or Firebase Cloud Messaging (FCM).
 
+> ** Track your campaigns:** The SDK automatically tracks delivery, opens, and clicks. For advanced tracking customization and implementation details, see [Push Notification Tracking](#push-notification-tracking).
+
 ### Prerequisites
 
 Before implementing push notifications:
@@ -1102,8 +1099,7 @@ const handleLogin = async (userId: string, userEmail: string) => {
 **Important Notes:**
 - When users start the app, they automatically generate a device token
 - This token links to their Zixflow profile when you call `identify()`
-- Device tokens are automatically removed from previous profiles when identifying new users
-- This prevents duplicate notifications when users switch accounts
+- This ensures notifications are delivered to the correct user
 
 #### Step 5: Get Device Token
 
@@ -1430,94 +1426,418 @@ Zixflow.initialize(config);
 
 ---
 
-### Next Steps
+---
+
+## Push Notification Tracking
+
+### Overview
+
+Zixflow automatically tracks push notification delivery and engagement metrics to help you measure campaign performance. The SDK tracks three key lifecycle events:
+
+1. **Delivery Confirmed** - When the notification arrives on the device
+2. **Notification Opened** - When the user taps the notification
+3. **Action Button Clicked** - When the user taps an action button
+
+### How Push Tracking Works
+
+When Zixflow sends a push notification, it includes special tracking fields in the data payload:
+
+| Field | Purpose |
+|-------|---------|
+| `Zixflow-Delivery-ID` | Unique ID for this delivery (links to campaign record) |
+| `Zixflow-Delivery-Token` | The FCM/APNs token the notification was sent to |
 
-- Learn about [In-App Messaging](#in-app-messaging)
-- Explore [Deep Link Handling](#deep-links-and-navigation)
-- See [Example Applications](#example-applications) for complete implementations
+**Example push payload:**
+```json
+{
+  "Zixflow-Delivery-ID": "626533406292836846",
+  "Zixflow-Delivery-Token": "dcFRlDhiRbehM1vg...",
+  "title": "Flash Sale! 70% OFF",
+  "body": "Limited time only — grab your deal now!",
+  "deeplink_url": "https://yourapp.com/sale",
+  "image_url": "https://cdn.yourapp.com/banner.png",
+  "action_buttons": "[{\"name\":\"Shop Now\",\"deeplink\":\"https://yourapp.com/sale\"},{\"name\":\"Remind Me\",\"deeplink\":\"\"}]"
+}
+```
+
+> **Note:** The SDK automatically handles most tracking for you when using the default push implementation. This section covers advanced customization scenarios.
 
 ---
 
-## In-App Messaging
+### Tracking Events
+
+#### 1. Delivery Confirmed
 
-### Event Listeners
+**When to track:** The moment the push payload arrives on the device
 
-Register event listeners to respond to in-app message events:
+**SDK method:** `Zixflow.trackMetric({ deliveryID, deviceToken, event: MetricEvent.delivered })`
+
+**Implementation:**
 
 ```typescript
-import { Zixflow, InAppMessageEvent, InAppMessageEventType } from 'zixflow-reactnative';
-import { useEffect } from 'react';
+import messaging from '@react-native-firebase/messaging';
+import { Zixflow, MetricEvent } from 'zixflow-reactnative';
 
-export default function App() {
-  useEffect(() => {
-    const inAppMessaging = Zixflow.inAppMessaging;
+// Listen for foreground messages
+useEffect(() => {
+  const unsubscribe = messaging().onMessage(async (remoteMessage) => {
+    const deliveryId = remoteMessage.data?.['Zixflow-Delivery-ID'] ?? '';
+    const deliveryToken = remoteMessage.data?.['Zixflow-Delivery-Token'] ?? cachedToken ?? '';
+
+    if (deliveryId && deliveryToken) {
+      await Zixflow.trackMetric({
+        deliveryID: deliveryId,
+        deviceToken: deliveryToken,
+        event: MetricEvent.delivered,
+      });
+    }
+  });
 
-    const eventListener = inAppMessaging.registerEventsListener((event: InAppMessageEvent) => {
-      switch (event.eventType) {
-        case InAppMessageEventType.messageShown:
-          console.log('In-app message shown', event);
-          break;
+  return unsubscribe;
+}, []);
+```
 
-        case InAppMessageEventType.messageDismissed:
-          console.log('In-app message dismissed', event);
-          break;
+> **Important:** The Zixflow SDK automatically tracks delivery. Manual tracking is only needed for custom implementations.
 
-        case InAppMessageEventType.messageActionTaken:
-          console.log('Action taken on in-app message', event);
-          handleMessageAction(event);
-          break;
+---
 
-        case InAppMessageEventType.errorWithMessage:
-          console.error('Error with in-app message', event);
-          break;
+#### 2. Notification Opened
+
+**When to track:** When the user taps the notification banner
+
+**SDK method:** `Zixflow.trackMetric({ deliveryID, deviceToken, event: MetricEvent.opened })`
+
+**Implementation:**
+
+```typescript
+import messaging from '@react-native-firebase/messaging';
+import { Zixflow, MetricEvent } from 'zixflow-reactnative';
+
+// Background / quit tap
+useEffect(() => {
+  const unsubscribe = messaging().onNotificationOpenedApp(async (remoteMessage) => {
+    trackOpened(remoteMessage.data);
+    handleDeeplink(remoteMessage.data?.deeplink_url);
+  });
+
+  return unsubscribe;
+}, []);
+
+// Terminated tap
+useEffect(() => {
+  messaging()
+    .getInitialNotification()
+    .then((remoteMessage) => {
+      if (remoteMessage) {
+        trackOpened(remoteMessage.data);
+        handleDeeplink(remoteMessage.data?.deeplink_url);
       }
     });
+}, []);
 
-    // Cleanup listener on unmount
-    return () => {
-      eventListener.remove();
-    };
+const trackOpened = async (data: any) => {
+  const deliveryId = data?.['Zixflow-Delivery-ID'] ?? '';
+  const deliveryToken = data?.['Zixflow-Delivery-Token'] ?? cachedToken ?? '';
+
+  if (deliveryId && deliveryToken) {
+    await Zixflow.trackMetric({
+      deliveryID: deliveryId,
+      deviceToken: deliveryToken,
+      event: MetricEvent.opened,
+    });
+  }
+};
+```
+
+> **Note:** The SDK automatically tracks opens when using the default push implementation.
+
+---
+
+#### 3. Action Button Clicked
+
+**When to track:** When the user taps a named action button
+
+**SDK method:** `Zixflow.track({ name: "Push Notification Action Clicked", properties: {...} })`
+
+**Implementation:**
+
+```typescript
+import { Zixflow, MetricEvent } from 'zixflow-reactnative';
+
+// Handle action press from local notification
+const handleActionPress = async (data: any, actionId: string) => {
+  const deliveryId = data['Zixflow-Delivery-ID'] ?? '';
+  const token = data['Zixflow-Delivery-Token'] ?? '';
+  const actionIndex = parseInt(actionId.replace(/\D/g, ''), 10);
+  const buttons = parseButtons(data['action_buttons']);
+  const actionName = buttons[actionIndex]?.name ?? `Action ${actionIndex + 1}`;
+  const actionDeeplink = buttons[actionIndex]?.deeplink ?? '';
+
+  // Always fire opened first
+  await Zixflow.trackMetric({
+    deliveryID: deliveryId,
+    deviceToken: token,
+    event: MetricEvent.opened,
+  });
+
+  // Then fire action clicked
+  await Zixflow.track({
+    name: 'Push Notification Action Clicked',
+    properties: {
+      'Zixflow-Delivery-ID': deliveryId,
+      'Zixflow-Delivery-Token': token,
+      'action_index': actionIndex,
+      'action_name': actionName,
+      'action_deeplink': actionDeeplink,
+    },
+  });
+};
+
+const parseButtons = (raw: any) => {
+  if (!raw) return [];
+  try {
+    return typeof raw === 'string' ? JSON.parse(raw) : raw;
+  } catch {
+    return [];
+  }
+};
+```
+
+**Action button properties:**
+
+| Property | Type | Required | Description |
+|----------|------|----------|-------------|
+| `Zixflow-Delivery-ID` | string | ✅ | Links event to campaign delivery |
+| `action_index` | integer | ✅ | 0-based index of button tapped |
+| `action_name` | string | ✅ | Button label (e.g., "Shop Now") |
+| `Zixflow-Delivery-Token` | string | Recommended | FCM/APNs token |
+| `action_deeplink` | string | Recommended | Button's URL |
+
+---
+
+### Action Buttons Format
+
+The `action_buttons` field is a JSON-encoded string containing button definitions:
+
+**Raw payload value:**
+```
+"[{\"name\":\"Shop Now\",\"deeplink\":\"https://yourapp.com/sale\"},{\"name\":\"Remind Me\",\"deeplink\":\"\"}]"
+```
+
+**Parsed structure:**
+```json
+[
+  { "name": "Shop Now",  "deeplink": "https://yourapp.com/sale" },
+  { "name": "Remind Me", "deeplink": "" }
+]
+```
+
+**Parsing example:**
+
+```typescript
+const parseActionButtons = (raw: any): Array<{ name: string; deeplink: string }> => {
+  if (!raw) return [];
+
+  try {
+    const decoded = typeof raw === 'string' ? JSON.parse(raw) : raw;
+    return Array.isArray(decoded) ? decoded : [];
+  } catch (error) {
+    console.error('Error parsing action buttons:', error);
+    return [];
+  }
+};
+
+// Usage
+const buttons = parseActionButtons(remoteMessage.data?.action_buttons);
+buttons.forEach((btn, index) => {
+  console.log(`Button ${index}: ${btn.name} -> ${btn.deeplink}`);
+});
+```
+
+**Rules:**
+- Maximum 2 buttons per notification (recommended for consistency across platforms)
+- `deeplink` may be empty — handle gracefully
+- Button index is 0-based (first button = index 0)
+
+---
+
+### Complete Push Tracking Implementation
+
+Here's a complete example integrating all tracking events:
+
+```typescript
+import React, { useEffect, useState } from 'react';
+import messaging, { FirebaseMessagingTypes } from '@react-native-firebase/messaging';
+import { Zixflow, MetricEvent } from 'zixflow-reactnative';
+
+const App = () => {
+  const [fcmToken, setFcmToken] = useState<string | null>(null);
+
+  useEffect(() => {
+    setupPushNotifications();
   }, []);
 
+  const setupPushNotifications = async () => {
+    // Request permission
+    const authStatus = await messaging().requestPermission();
+    const enabled =
+      authStatus === messaging.AuthorizationStatus.AUTHORIZED ||
+      authStatus === messaging.AuthorizationStatus.PROVISIONAL;
+
+    if (enabled) {
+      // Get FCM token
+      const token = await messaging().getToken();
+      setFcmToken(token);
+
+      // Register with Zixflow
+      await Zixflow.registerDeviceToken({ deviceToken: token });
+
+      // Listen for token refresh
+      messaging().onTokenRefresh(async (newToken) => {
+        setFcmToken(newToken);
+        await Zixflow.registerDeviceToken({ deviceToken: newToken });
+      });
+
+      // Handle foreground messages
+      messaging().onMessage(async (remoteMessage) => {
+        trackDelivery(remoteMessage);
+        showLocalNotification(remoteMessage);
+      });
+
+      // Handle background/quit taps
+      messaging().onNotificationOpenedApp((remoteMessage) => {
+        trackOpened(remoteMessage.data);
+        handleDeeplink(remoteMessage.data?.deeplink_url);
+      });
+
+      // Handle terminated tap
+      const initialNotification = await messaging().getInitialNotification();
+      if (initialNotification) {
+        trackOpened(initialNotification.data);
+        handleDeeplink(initialNotification.data?.deeplink_url);
+      }
+    }
+  };
+
+  const trackDelivery = async (message: FirebaseMessagingTypes.RemoteMessage) => {
+    const deliveryId = message.data?.['Zixflow-Delivery-ID'] ?? '';
+    const deliveryToken = message.data?.['Zixflow-Delivery-Token'] ?? fcmToken ?? '';
+
+    if (deliveryId && deliveryToken) {
+      await Zixflow.trackMetric({
+        deliveryID: deliveryId,
+        deviceToken: deliveryToken,
+        event: MetricEvent.delivered,
+      });
+    }
+  };
+
+  const trackOpened = async (data: any) => {
+    const deliveryId = data?.['Zixflow-Delivery-ID'] ?? '';
+    const deliveryToken = data?.['Zixflow-Delivery-Token'] ?? fcmToken ?? '';
+
+    if (deliveryId && deliveryToken) {
+      await Zixflow.trackMetric({
+        deliveryID: deliveryId,
+        deviceToken: deliveryToken,
+        event: MetricEvent.opened,
+      });
+    }
+  };
+
+  const handleDeeplink = (url?: string) => {
+    if (!url) return;
+    // Implement your deep link navigation logic
+    console.log('Navigating to:', url);
+  };
+
+  const showLocalNotification = async (message: FirebaseMessagingTypes.RemoteMessage) => {
+    // Use local notification library to show notification
+  };
+
   return (
     // Your app UI
+    <></>
   );
-}
+};
+
+export default App;
 ```
 
-### Message Events
+---
+
+### Tracking Decision Flowchart
 
-The SDK provides the following in-app message event types:
+```
+Notification received?
+├── YES → trackMetric(delivered)        [automatic with SDK]
+│
+User interacted?
+├── Tapped notification body
+│   └── trackMetric(opened)             [automatic with SDK]
+│       └── Navigate to deeplink_url
+│
+└── Tapped action button
+    ├── trackMetric(opened)             [automatic with SDK]
+    └── track("Push Notification Action Clicked")
+        └── Navigate to button's deeplink
+```
 
-| Event Type | Description |
-|------------|-------------|
-| `messageShown` | Message was displayed to the user |
-| `messageDismissed` | Message was dismissed by the user |
-| `messageActionTaken` | User took an action on the message (clicked button, link, etc.) |
-| `errorWithMessage` | Error occurred while displaying the message |
+---
 
-**Event properties**:
-- `eventType`: The type of event
-- `deliveryId`: Unique delivery identifier
-- `messageId`: Message template identifier
-- `actionName`: Name of the action taken (for `messageActionTaken`)
-- `actionValue`: Value of the action (for `messageActionTaken`)
+### Fallback for Non-Zixflow Push
 
-### Dismissing Messages
+If a push notification doesn't contain `Zixflow-Delivery-ID` (sent from another source), the SDK automatically skips tracking.
 
-Programmatically dismiss the current in-app message:
+For custom analytics on non-Zixflow pushes, use a different event name:
 
 ```typescript
-import { Zixflow } from 'zixflow-reactnative';
+// Don't use reserved push event names for non-Zixflow pushes
+await Zixflow.track({
+  name: 'External Push Received',
+  properties: {
+    'notification_id': message.messageId ?? '',
+    'title': message.notification?.title ?? '',
+    'body': message.notification?.body ?? '',
+    'source': 'external',
+  },
+});
+```
 
-const handleMessageAction = (event: InAppMessageEvent) => {
-  if (event.actionValue === 'dismiss' || event.actionValue === 'close') {
-    // Dismiss the message
-    Zixflow.inAppMessaging.dismissMessage();
-  }
+> **Important:** Push notification event names (`Push Notification Delivered`, `Push Notification Opened`, `Push Notification Action Clicked`) are reserved for Zixflow's delivery pipeline.
+
+---
+
+### Testing Push Tracking
+
+#### Verify Tracking Events
+
+Enable debug logging to see tracking events:
+
+```typescript
+const config: ZixflowConfig = {
+  apiKey: 'YOUR_API_KEY',
+  logLevel: 'debug',
 };
+
+await Zixflow.setup(config);
 ```
 
+Look for these log messages:
+- `[Zixflow] Push Notification Delivered tracked`
+- `[Zixflow] Push Notification Opened tracked`
+- `[Zixflow] Push Notification Action Clicked tracked`
+
+#### Check Campaign Analytics
+
+1. Log into Zixflow dashboard
+2. Navigate to **Messaging** → **Push Notifications**
+3. View campaign metrics:
+   - **Sent** - Total notifications sent
+   - **Delivered** - Arrived on device
+   - **Opened** - User tapped notification
+   - **Clicked** - User tapped action button
+
 ---
 
 ## Location Tracking
@@ -1561,249 +1881,334 @@ const requestLocationPermission = async () => {
 };
 ```
 
----
-
-## Advanced Configuration
+On iOS, a React Native 0.88+ `UIScene` host using the acknowledged handler must declare that ownership before React Native starts. This API is not used on Android or by AppDelegate-only hosts. Call this first in `scene(_:willConnectTo:options:)` so cold destinations wait for the JavaScript handler instead of entering the legacy `Linking` path:
 
-### Region Settings
+```swift
+NativeZixflow.configureAcknowledgedSceneDeepLinkRouting()
+```
 
-Configure the data center region for data residency:
+Register the app's Zixflow deep-link handler before calling `Zixflow.initialize`. Return
+`true` after routing a URL. Return `false` to let the native SDK try the host AppDelegate, then pass
+a host-owned custom scheme to React Native `Linking` or open other URLs through the system. If your
+handler might decline an app-owned custom scheme, keep a `Linking` URL listener registered for that
+fallback. A thrown error, rejected promise, missing handler, or handler timeout follows the same
+native fallback. Cold URLs wait up to ten seconds for registration and are replayed once the handler
+is ready. After delivery, the handler has ten seconds to settle. If it takes longer, native fallback
+runs; a handler that later routes the URL can cause a second navigation because its acknowledgement
+cannot cancel the fallback.
 
 ```typescript
-import { Zixflow } from 'zixflow-reactnative';
+const subscription = Zixflow.setDeepLinkHandler(async (url) => {
+  if (!canRouteInApp(url)) {
+    return false;
+  }
 
-const config = {
-  apiKey: 'YOUR_API_KEY',
-  // or 
-};
+  await routeInApp(url);
+  return true;
+});
 
 Zixflow.initialize(config);
 ```
 
-**Available regions**:
-- `` - United States data center
-- `` - European Union data center
+Remove the returned subscription when the routing owner is torn down. If no replacement handler
+registers, later destinations wait for the readiness timeout and then use the native fallback.
 
-### Log Levels
-
-Control SDK logging for debugging:
+The existing `Linking` path remains available for backward compatibility. Keep
+`NativeZixflow.configureSceneDeepLinkRouting()` in your SceneDelegate, then signal readiness
+after registering the listener:
 
 ```typescript
-import { Zixflow, ZixflowLogLevel } from 'zixflow-reactnative';
-
-const config = {
-  apiKey: 'YOUR_API_KEY',
-  logLevel: ZixflowLogLevel.debug,  // debug, info, error, none
-};
-
-Zixflow.initialize(config);
+const subscription = Linking.addEventListener('url', ({ url }) => {
+  // Route the URL in your app.
+});
+Zixflow.setDeepLinkRoutingReady();
 ```
 
-**Log levels**:
-- `ZixflowLogLevel.debug` - Verbose logging (development)
-- `ZixflowLogLevel.info` - Informational messages
-- `ZixflowLogLevel.error` - Errors only
-- `ZixflowLogLevel.none` - No logging (production)
+Cold destinations wait up to ten seconds for this readiness signal. If it does not arrive, the SDK
+tries the host AppDelegate, passes a host-owned custom scheme to React Native `Linking`, or opens
+other URLs through the system.
 
-### Auto-Tracking Options
+This older path cannot acknowledge whether JavaScript handled the URL, so the SDK cannot safely fall back after it publishes a `Linking` event. Prefer `setDeepLinkHandler` for new UIScene integrations. Older React Native versions and AppDelegate-only hosts keep their existing deep-link integration.
 
-Configure automatic tracking features:
+Expo apps keep the `Linking` path. With config-plugin auto-initialization, register the app's
+`Linking` listener, then call `Zixflow.setDeepLinkRoutingReady()` after the router is ready. The
+Expo plugin configures its native scene lifecycle automatically, so Expo app code does not call a
+native configuration method. Apps using JavaScript initialization register the router before
+`Zixflow.initialize`; initialization marks Linking ready automatically.
 
-```typescript
-import { Zixflow } from 'zixflow-reactnative';
+This integration applies after the host has adopted React Native's UIScene lifecycle; the plugin does not replace React Native's root application lifecycle.
 
-const config = {
-  apiKey: 'YOUR_API_KEY',
+This release's compatibility scope is one simultaneous window scene. Multiple simultaneous React Native window scenes are not supported. React Native's URL notification is process-wide, so SDK-published destinations may reach every connected React Native instance rather than one selected window.
 
-  // Automatically track device attributes (OS, model, app version)
-  autoTrackDeviceAttributes: true,
+---
 
-  // Automatically track app lifecycle events (open, close, background)
-  trackApplicationLifecycleEvents: true,
+## Geofence Tracking
 
-  // Automatically track screens (requires integration)
-  autoTrackScreenViews: true,
-};
+Geofence is an optional module, off by default. Enabling it also enables the Location module, which geofence depends on.
 
-Zixflow.initialize(config);
+Enable it at build time:
+
+```properties
+# android/gradle.properties
+zixflow_geofence_enabled=true
 ```
 
-### Custom API Hosts
+```ruby
+# ios/Podfile
+pod 'zixflow-reactnative', :subspecs => ['geofence']
+```
 
-Override API endpoints for testing or custom infrastructure:
+Then opt in by passing a `geofence` config to `initialize`:
 
 ```typescript
-import { Zixflow } from 'zixflow-reactnative';
+import { Zixflow, ZixflowGeofenceLocationMode } from 'zixflow-reactnative';
 
-const config = {
+Zixflow.initialize({
   apiKey: 'YOUR_API_KEY',
+  geofence: {
+    // AUTOMATIC (default): the SDK acquires location itself on identify and app launch.
+    // MANUAL: drive refreshes yourself via Zixflow.geofence.refreshFromCurrentLocation().
+    locationMode: ZixflowGeofenceLocationMode.Automatic,
+  },
+  ios: {
+    // Whether geofence transitions are delivered in real time on a background cold-wake.
+    // Defaults to on when the geofence module is enabled.
+    allowBackgroundDelivery: true,
+  },
+});
+```
 
-  // Custom tracking API host
-  trackingApiUrl: 'https://custom-track.zixflow.com',
+Request location permissions the same way as for [Location Tracking](#location-tracking) above — geofence monitoring requires them and the SDK never requests permission itself.
 
-  // Custom in-app messaging API host
-  inApp: {
-        // Override in-app messaging API endpoint if needed
-  },
-};
+With `MANUAL` location mode, trigger a refresh after permission is granted:
 
-Zixflow.initialize(config);
+```typescript
+Zixflow.geofence.refreshFromCurrentLocation();
 ```
 
----
+This requests a one-shot location fix and refreshes the nearby geofence set from it. It no-ops if the geofence module is not enabled or a user has not been identified.
 
-## Troubleshooting
+---
 
-### Installation Issues
+## 🔴 Live Activities
 
-**Issue**: `npm install` fails with dependency conflicts
+Enable the activity types you use under the `liveNotifications` key of your SDK config. On iOS, also add `NSSupportsLiveActivities` to your app's `Info.plist`, the `liveactivities` pod subspec, and a Widget Extension that renders the SDK's built-in templates. Without the `Info.plist` key, iOS refuses to start any activity:
 
-**Solution**: Use `--legacy-peer-deps` flag:
-```bash
-npm install zixflow-reactnative --legacy-peer-deps
+```xml
+<key>NSSupportsLiveActivities</key>
+<true/>
 ```
 
-Or with Yarn:
-```bash
-yarn add zixflow-reactnative --legacy-peer-deps
+**One manual step is required on iOS.** Forward every opened URL to the SDK from the host's active lifecycle, or taps on a Live Activity are not attributed. `NativeLiveActivities` comes from the wrapper pod, so import it. This only compiles once the `liveactivities` subspec is installed.
+
+For an AppDelegate host:
+
+```swift
+import zixflow_reactnative
+import React
+
+extension AppDelegate {
+  func application(_ app: UIApplication, open url: URL, options: [UIApplication.OpenURLOptionsKey: Any] = [:]) -> Bool {
+    // Reports an `opened` metric and returns the deep link to route to. A non-Zixflow URL comes
+    // back unchanged; `nil` means the activity carried no deep link, so there is nothing to open.
+    guard let routableUrl = NativeLiveActivities.handleWidgetUrl(url) else { return true }
+    return RCTLinkingManager.application(app, open: routableUrl, options: options)
+  }
+}
 ```
 
----
+A React Native `AppDelegate` conforms to `UIApplicationDelegate` directly rather than subclassing, so this method is not an `override`, and the URL is passed on to `RCTLinkingManager` instead of `super`. See [the sample app's `AppDelegate.swift`](/example/ios/SampleApp/AppDelegate.swift) for this in context.
 
-**Issue**: Auto-linking fails after installation
+For a `UIScene` host, handle both lifecycle paths. At scene connection, pass the connection options through the wrapper so a cold Live Activity tap is attributed and its destination enters the acknowledged Zixflow router. Ordinary app links remain in React Native launch options for `Linking`:
 
-**Solution**: Try manual linking:
+```swift
+import zixflow_reactnative
 
-1. Clean the build:
-```bash
-cd android && ./gradlew clean && cd ..
-cd ios && rm -rf Pods && pod install && cd ..
+reactNativeFactory?.startReactNative(
+  withModuleName: "YourApp",
+  in: window,
+  launchOptions: NativeLiveActivities.reactNativeLaunchOptions(from: connectionOptions)
+)
 ```
 
-2. Rebuild the app:
-```bash
-npx react-native run-ios
-npx react-native run-android
+Then replace the ordinary React Native URL-forwarding body in the existing `SceneDelegate` for warm opens. This reports Live Activity taps, sends Zixflow destinations through the configured Zixflow router, and forwards ordinary app links to React Native `Linking`:
+
+```swift
+import zixflow_reactnative
+
+func scene(_ scene: UIScene, openURLContexts URLContexts: Set<UIOpenURLContext>) {
+  for context in URLContexts {
+    NativeLiveActivities.handleAndRouteWidgetUrl(context.url)
+  }
+}
 ```
 
-### iOS Build Errors
+Do not also pass those URLs to `RCTLinkingManager`. The helper already routes them through the
+Zixflow bridge, and forwarding them again can deliver the same URL twice.
 
-**Issue**: `Module 'Zixflow' not found`
+Android needs no equivalent native step.
 
-**Solution**:
-1. Ensure you've run `pod install` in the `ios` directory
-2. Clean build folder in Xcode: Product > Clean Build Folder
-3. Rebuild the project
+For Expo Router, unwrap the URL once in the app's top-level `app/+native-intent.tsx` file:
 
----
+```typescript
+import { Zixflow } from 'zixflow-reactnative';
 
-**Issue**: Swift compiler errors in native modules
+export async function redirectSystemPath({ path }: { path: string }) {
+  return Zixflow.liveActivities.handleWidgetUrl(path);
+}
+```
 
-**Solution**:
-1. Check Xcode version (14.0+ required)
-2. Update CocoaPods: `sudo gem install cocoapods`
-3. Update pod dependencies: `cd ios && pod update && cd ..`
+This reports the opened event, returns the customer's destination, preserves ordinary URLs, and
+returns `null` for a Zixflow tracking URL without a destination. Do not also call the helper
+from a `Linking` listener because processing the same tracking URL twice reports two opened events.
+Expo apps without Expo Router can apply the helper once in their central `Linking` initial-URL and
+subscription pipeline.
 
 ---
 
-**Issue**: Notification Service Extension not working
+## Notification Inbox
 
-**Solution**:
-1. Ensure the extension target has the correct dependencies in Podfile
-2. Run `pod install` after adding the extension
-3. Check that the extension's deployment target is iOS 13.0+
-4. Verify the extension is added to your app's target dependencies
+The Visual Notification Inbox renders received messages in a list the SDK owns the design of. Two components are available:
 
-### Android Build Errors
+- `NotificationInboxBellView` — a bell icon with an unread badge. Tapping it opens the SDK's own inbox panel; the host presents nothing.
+- `NotificationInboxView` — the message list itself, embeddable directly in your own screen with no surrounding chrome (no bell, no scrim).
 
-**Issue**: `Cannot find symbol class Zixflow`
+```tsx
+import { NotificationInboxBellView, NotificationInboxView } from 'zixflow-reactnative';
 
-**Solution**:
-1. Clean Gradle cache:
-```bash
-cd android && ./gradlew clean && cd ..
-```
+// Place the bell wherever your layout calls for it. Give it a fixed size for
+// predictable layout — at least 88 points/dp square.
+<NotificationInboxBellView
+  style={{ width: 88, height: 88 }}
+  onTap={() => analytics.track('inbox_bell_tapped')}
+/>
 
-2. Rebuild the app:
-```bash
-npx react-native run-android
+// Or embed the message list directly in a screen of your own.
+<NotificationInboxView style={{ flex: 1 }} />
 ```
 
----
+`onTap` on `NotificationInboxBellView` is observational only — the SDK opens the inbox panel itself. Message actions inside `NotificationInboxView` are reported through the global inbox event listener below, not a per-message callback.
 
-**Issue**: Duplicate class errors with Firebase
+Remote branding styles the bell and list themselves (colors, icon); the host still owns layout and placement via `style`.
 
-**Solution**:
-1. Check that you're not including Firebase dependencies manually if using FCM
-2. Ensure all Firebase dependencies use the same version
-3. Add to `android/gradle.properties`:
-```properties
-android.enableJetifier=true
+The SDK ships no text of its own in the visual inbox, so accessibility labels are the one place a string is still needed. Every label is optional — an omitted label leaves that element unlabeled rather than falling back to English:
+
+```typescript
+Zixflow.initialize({
+  apiKey: 'YOUR_API_KEY',
+  inApp: {
+    notificationInboxAccessibilityLabels: {
+      bell: t('inbox.bell'),
+      bellWithUnreadCount: t('inbox.unread'), // e.g. "{count} unread notifications"
+      loadingIndicator: t('inbox.loading'),
+      emptyState: t('inbox.empty'),
+    },
+  },
+});
 ```
 
----
+Register a listener to observe inbox events (shown, opened, dismissed, and non-dismiss actions taken on a message):
 
-**Issue**: Minimum SDK version error
+```typescript
+import { InboxEventType } from 'zixflow-reactnative';
+
+const subscription = Zixflow.inAppMessaging.registerInboxEventListener((event) => {
+  switch (event.eventType) {
+    case InboxEventType.messageActionTaken:
+      // event.actionName / event.actionValue are only present for this event
+      console.log('Inbox action taken:', event.actionName, event.actionValue);
+      break;
+    case InboxEventType.messageShown:
+    case InboxEventType.messageOpened:
+    case InboxEventType.messageDismissed:
+      console.log(event.eventType, event.message);
+      break;
+  }
+});
 
-**Solution**: Update `android/build.gradle`:
-```gradle
-ext {
-    minSdkVersion = 24
-}
+// Remove listener
+subscription.remove();
 ```
 
-### Push Notification Issues
+You can also fetch and manage inbox messages directly through `Zixflow.inAppMessaging.inbox()`:
 
-**Issue**: Push notifications not received on iOS
+```typescript
+const inbox = Zixflow.inAppMessaging.inbox();
 
-**Checklist**:
-- [ ] Push Notifications capability enabled in Xcode
-- [ ] APNs certificate uploaded to Zixflow dashboard
-- [ ] Device token registered (check logs)
-- [ ] Permission granted by user
-- [ ] App not in foreground (notifications shown in background/killed state)
+const messages = await inbox.getMessages();
+
+inbox.markMessageOpened(message);
+inbox.markMessageDeleted(message);
+```
 
 ---
 
-**Issue**: Push notifications not received on Android
+## Advanced Configuration
 
-**Checklist**:
-- [ ] `google-services.json` file added to `android/app/`
-- [ ] Google Services plugin applied in `android/app/build.gradle`
-- [ ] FCM server key uploaded to Zixflow dashboard
-- [ ] Device registered for push (check logs)
-- [ ] Notification permissions granted (Android 13+)
+### Log Levels
 
----
+Control SDK logging for debugging:
 
-**Issue**: Rich push notifications (images) not working
+```typescript
+import { Zixflow, ZixflowLogLevel } from 'zixflow-reactnative';
 
-**Solution**: Ensure Notification Service Extension is properly configured on iOS (see [Notification Service Extension](#notification-service-extension))
+const config = {
+  apiKey: 'YOUR_API_KEY',
+  logLevel: ZixflowLogLevel.debug,  // debug, info, error, none
+};
 
-### In-App Message Issues
+Zixflow.initialize(config);
+```
 
-**Issue**: In-app messages not displaying
+**Log levels**:
+- `ZixflowLogLevel.debug` - Verbose logging (development)
+- `ZixflowLogLevel.info` - Informational messages
+- `ZixflowLogLevel.error` - Errors only
+- `ZixflowLogLevel.none` - No logging (production)
 
-**Checklist**:
-- [ ] In-app messaging module initialized
-- [ ] Event listener registered
-- [ ] User identified before triggering message
-- [ ] Message created and published in Zixflow dashboard
-- [ ] Check logs for error events
+### Auto-Tracking Options
 
----
+Configure automatic tracking features:
+
+```typescript
+import { Zixflow } from 'zixflow-reactnative';
+
+const config = {
+  apiKey: 'YOUR_API_KEY',
+
+  // Automatically track device attributes (OS, model, app version)
+  autoTrackDeviceAttributes: true,
+
+  // Automatically track app lifecycle events (open, close, background)
+  trackApplicationLifecycleEvents: true,
+
+  // Automatically track screens (requires integration)
+  autoTrackScreenViews: true,
+};
 
-**Issue**: In-app message events not firing
+Zixflow.initialize(config);
+```
+
+### Custom API Hosts
+
+Override API endpoints for testing or custom infrastructure:
 
-**Solution**: Ensure event listener is registered before messages are triggered:
 ```typescript
-useEffect(() => {
-  const listener = Zixflow.inAppMessaging.registerEventsListener((event) => {
-    console.log('In-app event:', event);
-  });
+import { Zixflow } from 'zixflow-reactnative';
 
-  return () => listener.remove();
-}, []);
+const config = {
+  apiKey: 'YOUR_API_KEY',
+
+  // Custom tracking API host
+  trackingApiUrl: 'https://custom-track.zixflow.com',
+
+  // Custom in-app messaging API host
+  inApp: {
+        // Override in-app messaging API endpoint if needed
+  },
+};
+
+Zixflow.initialize(config);
 ```
 
 ---
@@ -1950,7 +2355,6 @@ Configuration object for SDK initialization.
 ```typescript
 interface ZixflowConfig {
   apiKey: string;
-  region?: Region;
   logLevel?: ZixflowLogLevel;
   inApp?: {
   };
@@ -1961,17 +2365,6 @@ interface ZixflowConfig {
 }
 ```
 
-#### `Region`
-
-Data center region enum.
-
-```typescript
-enum Region {
-  US = 'US',
-  EU = 'EU'
-}
-```
-
 #### `ZixflowLogLevel`
 
 Log level enum.
@@ -2024,26 +2417,3 @@ interface InAppMessageEvent {
 }
 ```
 
----
-
-## Support & Resources
-
-### Documentation
-
-- **GitHub Repository**: https://github.com/zixflow/zixflow-reactnative
-- **iOS SDK Documentation**: https://github.com/zixflow/zixflow-ios
-- **Android SDK Documentation**: https://github.com/zixflow/zixflow-android
-- **API Reference**: See [API Reference](#api-reference) section above
-
-### Getting Help
-
-- **GitHub Issues**: https://github.com/zixflow/zixflow-reactnative/issues
-- **Support Email**: support@zixflow.com
-
-### Changelog
-
-See [CHANGELOG.md](../CHANGELOG.md) for version history and release notes.
-
----
-
-**Need help?** Contact our support team at support@zixflow.com or open an issue on GitHub.