zixflow-reactnative 1.1.2 → 1.1.4

package/README.md

@@ -1,446 +1,2238 @@
-<p align="center">
-  <a href="https://zixflow.com">
-    <img src="https://zixflow.com/logo.svg" height="60">
-  </a>
-</p>
+# Zixflow React Native SDK - Integration Guide
 
-[![npm version](https://img.shields.io/npm/v/zixflow-reactnative.svg)](https://www.npmjs.com/package/zixflow-reactnative)
-[![npm downloads](https://img.shields.io/npm/dm/zixflow-reactnative)](https://www.npmjs.com/package/zixflow-reactnative)
-![min Android SDK version is 21](https://img.shields.io/badge/min%20Android%20SDK-21-green)
-![min iOS version is 13](https://img.shields.io/badge/min%20iOS%20version-13-blue)
-![min Swift version is 5.3](https://img.shields.io/badge/min%20Swift%20version-5.3-orange)
-[![Contributor Covenant](https://img.shields.io/badge/Contributor%20Covenant-2.0-4baaaa.svg)](CODE_OF_CONDUCT.md)
+Welcome to the **Zixflow React Native SDK** integration guide. This comprehensive document will help you install, configure, and use the Zixflow SDK in your React Native application to track user behavior, send push notifications, display in-app messages, and more.
 
-# Zixflow React Native SDK
+---
+
+## Table of Contents
+
+1. [Introduction](#introduction)
+2. [Requirements](#requirements)
+3. [Installation](#installation)
+   - [npm Installation](#npm-installation)
+   - [Yarn Installation](#yarn-installation)
+4. [iOS Setup](#ios-setup)
+   - [CocoaPods Integration](#cocoapods-integration)
+   - [Swift Package Manager Integration](#swift-package-manager-integration)
+   - [Push Notification Setup (APNs)](#push-notification-setup-apns)
+   - [Notification Service Extension](#notification-service-extension)
+5. [Android Setup](#android-setup)
+   - [Gradle Configuration](#gradle-configuration)
+   - [Firebase Cloud Messaging Setup](#firebase-cloud-messaging-setup)
+6. [Quick Start](#quick-start)
+   - [Basic Configuration](#basic-configuration)
+   - [SDK Initialization](#sdk-initialization)
+7. [Core Features](#core-features)
+   - [User Identification](#user-identification)
+   - [Event Tracking](#event-tracking)
+   - [Screen Tracking](#screen-tracking)
+   - [User Profile Attributes](#user-profile-attributes)
+   - [Device Attributes](#device-attributes)
+   - [Clearing User Identity](#clearing-user-identity)
+8. [Push Notifications](#push-notifications)
+   - [Requesting Permission](#requesting-permission)
+   - [Handling Push Notifications](#handling-push-notifications)
+   - [Device Token Registration](#device-token-registration)
+9. [Push Notification Tracking](#push-notification-tracking)
+10. [Location Tracking](#location-tracking)
+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)
+15. [Example Applications](#example-applications)
+16. [API Reference](#api-reference)
+
+---
+
+## Introduction
+
+The **Zixflow React Native SDK** enables you to:
+
+- **Identify users** and track their behavior across your app
+- **Send targeted push notifications** via Apple Push Notification service (APNs) or Firebase Cloud Messaging (FCM)
+- **Display in-app messages** to engage users at the right time
+- **Track user location** to enable location-based messaging
+- **Manage user profiles** with custom attributes
+- **Track events and screen views** automatically or manually
+
+The SDK is built on top of the native Zixflow iOS and Android SDKs, providing a unified TypeScript API for React Native applications.
+
+---
+
+## Requirements
+
+### React Native
+
+- **React Native**: 0.60.0 or higher
+- **React**: 16.8.0 or higher (for hooks support)
+
+### iOS
+
+- **iOS**: 13.0 or higher
+- **Xcode**: 14.0 or higher
+- **Swift**: 5.3 or higher
+- **CocoaPods**: 1.10.0 or higher (if using CocoaPods)
+
+### Android
+
+- **Android**: API level 24 (Android 7.0) or higher
+- **Kotlin**: 1.6.0 or higher
+- **Gradle**: 7.0 or higher
+
+### TypeScript (Recommended)
+
+- **TypeScript**: 4.0 or higher
+
+---
+
+## 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:
+
+```bash
+npm install zixflow-reactnative
+```
+
+### Yarn Installation
+
+Or install using Yarn:
+
+```bash
+yarn add zixflow-reactnative
+```
+
+After installation, proceed with platform-specific setup for iOS and Android.
+
+---
+
+## iOS Setup
+
+### CocoaPods Integration
+
+The Zixflow React Native SDK automatically integrates with the native iOS SDK via CocoaPods or Swift Package Manager. If you're using **React Native 0.60 or higher**, dependencies are auto-linked.
+
+1. **Navigate to the iOS directory**:
+
+```bash
+cd ios
+```
+
+2. **Install CocoaPods dependencies**:
+
+```bash
+pod install
+```
+
+3. **Open the workspace in Xcode**:
+
+```bash
+open YourApp.xcworkspace
+```
+
+The SDK will automatically include the necessary Zixflow iOS modules:
+- `ZixflowCommon`
+- `ZixflowDataPipelines`
+- `ZixflowMessagingPush`
+- `ZixflowMessagingPushAPN` (for APNs)
+- `ZixflowMessagingInApp`
+
+### Swift Package Manager Integration
+
+If you prefer **Swift Package Manager (SPM)**, you can configure your project to use the Zixflow iOS SDK directly:
+
+1. **Open your project in Xcode**
+2. **Go to File > Add Package Dependencies**
+3. **Enter the repository URL**:
+   ```
+   https://github.com/zixflow/zixflow-ios.git
+   ```
+4. **Select the version**: Use `1.0.0` or higher
+5. **Add the following modules** to your app target:
+   - `Zixflow` (umbrella module)
+   - `ZixflowDataPipelines`
+   - `ZixflowMessagingPushAPN`
+   - `ZixflowMessagingInApp`
+
+> **Note**: The example app uses SPM for the native iOS SDK integration. See `example/ios/Podfile` for reference.
+
+### Push Notification Setup (APNs)
+
+To enable **Apple Push Notifications (APNs)**:
+
+1. **Enable Push Notifications capability** in Xcode:
+   - Select your app target
+   - Go to **Signing & Capabilities**
+   - Click **+ Capability** and add **Push Notifications**
+
+2. **Enable Background Modes**:
+   - Add **Background Modes** capability
+   - Enable **Remote notifications**
+
+3. **Configure APNs certificates** in your Apple Developer account and upload them to Zixflow dashboard.
+
+### Notification Service Extension
+
+To support **rich push notifications** (images, videos, action buttons), you need to add a **Notification Service Extension**:
+
+1. **Create a Notification Service Extension** in Xcode:
+   - File > New > Target > Notification Service Extension
+   - Name it `NotificationServiceExtension`
+
+2. **Add Zixflow modules to the extension** in your `Podfile`:
+
+```ruby
+target 'NotificationServiceExtension' do
+  pod "ZixflowMessagingPushAPN", "~> 1.0"
+  pod "ZixflowMessagingPush", "~> 1.0"
+  pod "ZixflowDataPipelines", "~> 1.0"
+  pod "ZixflowCommon", "~> 1.0"
+  pod "AnalyticsSwiftZixflow", "1.7.3+zixflow.1"
+end
+```
+
+3. **Update `NotificationService.swift`**:
+
+```swift
+import UserNotifications
+import ZixflowMessagingPushAPN
+
+class NotificationService: UNNotificationServiceExtension {
+    var contentHandler: ((UNNotificationContent) -> Void)?
+    var bestAttemptContent: UNMutableNotificationContent?
+
+    override func didReceive(_ request: UNNotificationRequest, withContentHandler contentHandler: @escaping (UNNotificationContent) -> Void) {
+        self.contentHandler = contentHandler
+        bestAttemptContent = (request.content.mutableCopy() as? UNMutableNotificationContent)
+
+        // Use Zixflow to handle rich push
+        MessagingPushAPN.didReceive(request, withContentHandler: contentHandler)
+    }
+
+    override func serviceExtensionTimeWillExpire() {
+        if let contentHandler = contentHandler, let bestAttemptContent = bestAttemptContent {
+            contentHandler(bestAttemptContent)
+        }
+    }
+}
+```
+
+4. **Run `pod install`** again to install extension dependencies.
+
+---
+
+## Android Setup
+
+### Gradle Configuration
+
+The React Native auto-linking will handle most of the Android setup. However, you need to ensure the following:
+
+1. **Set minimum SDK version** in `android/build.gradle`:
+
+```gradle
+buildscript {
+    ext {
+        minSdkVersion = 24
+        compileSdkVersion = 34
+        targetSdkVersion = 34
+    }
+}
+```
+
+2. **Add Maven repositories** in `android/build.gradle`:
+
+```gradle
+allprojects {
+    repositories {
+        google()
+        mavenCentral()
+        maven { url 'https://s01.oss.sonatype.org/content/repositories/snapshots/' }
+    }
+}
+```
+
+The Zixflow Android SDK will be automatically included via the React Native module.
+
+### Firebase Cloud Messaging Setup
+
+To enable **Firebase Cloud Messaging (FCM)** for push notifications on Android:
+
+1. **Add Firebase to your project**:
+   - Go to [Firebase Console](https://console.firebase.google.com/)
+   - Add your Android app
+   - Download `google-services.json` and place it in `android/app/`
+
+2. **Add Google Services plugin** in `android/build.gradle`:
+
+```gradle
+buildscript {
+    dependencies {
+        classpath 'com.google.gms:google-services:4.4.2'
+    }
+}
+```
+
+3. **Apply the plugin** in `android/app/build.gradle`:
+
+```gradle
+apply plugin: 'com.google.gms.google-services'
+```
+
+4. **Configure FCM in the SDK** (shown in the initialization section below).
+
+---
+
+## Quick Start
+
+### Basic Configuration
+
+The SDK is configured using a `ZixflowConfig` object with several options:
+
+```typescript
+import { Zixflow, ZixflowConfig, ZixflowLogLevel } from 'zixflow-reactnative';
+
+const config: ZixflowConfig = {
+  apiKey: 'YOUR_API_KEY',
+  logLevel: ZixflowLogLevel.debug,
+  inApp: {
+      },
+  autoTrackDeviceAttributes: true,
+  trackApplicationLifecycleEvents: true,
+};
+```
+
+**Configuration Options**:
+
+| Option | Type | Required | Description |
+|--------|------|----------|-------------|
+| `apiKey` | string | Yes | Your Zixflow API key |
+| `logLevel` | `ZixflowLogLevel` | No | Logging level (debug, info, error, none) |
+| `inApp` | object | No | Enable in-app messaging (use empty object: {}) |
+| `autoTrackDeviceAttributes` | boolean | No | Automatically track device info |
+| `trackApplicationLifecycleEvents` | boolean | No | Automatically track app lifecycle |
+
+### SDK Initialization
+
+Initialize the SDK in your `App.tsx` or main component using `useEffect`:
+
+```typescript
+import React, { useEffect } from 'react';
+import { Zixflow, ZixflowConfig, ZixflowLogLevel } from 'zixflow-reactnative';
+
+export default function App() {
+  useEffect(() => {
+    // Configure the SDK
+    const config: ZixflowConfig = {
+      apiKey: 'YOUR_API_KEY',
+      logLevel: ZixflowLogLevel.debug,
+      inApp: {
+              },
+      autoTrackDeviceAttributes: true,
+      trackApplicationLifecycleEvents: true,
+    };
+
+    // Initialize the SDK
+    Zixflow.initialize(config);
+
+    console.log('Zixflow SDK initialized');
+  }, []);
+
+  return (
+    // Your app UI
+  );
+}
+```
+
+> **Important**: Initialize the SDK as early as possible in your app's lifecycle, ideally in the root component's `useEffect`.
+
+---
+
+## Core Features
+
+### User Identification
+
+Identify users to track their behavior across sessions and devices:
+
+```typescript
+import { Zixflow } from 'zixflow-reactnative';
+
+// Identify user with ID only
+Zixflow.identify({
+  userId: 'user-123'
+});
+
+// Identify user with traits
+Zixflow.identify({
+  userId: 'user-123',
+  traits: {
+    email: 'user@example.com',
+    firstName: 'John',
+    lastName: 'Doe',
+    plan: 'premium'
+  }
+});
+```
+
+**When to identify users**:
+- After successful login
+- When user information becomes available
+- After account creation
+
+### Event Tracking
+
+Track custom events to understand user behavior:
+
+```typescript
+import { Zixflow } from 'zixflow-reactnative';
+
+// Track event without properties
+Zixflow.track('button_clicked');
+
+// Track event with properties
+Zixflow.track('product_viewed', {
+  product_id: '12345',
+  product_name: 'Premium Plan',
+  category: 'subscription',
+  price: 29.99
+});
+
+// Track with Map (alternative syntax)
+const properties = new Map<string, any>();
+properties.set('item_count', 3);
+properties.set('total_amount', 89.97);
+Zixflow.track('checkout_completed', properties);
+```
+
+**Common events to track**:
+- User actions (button clicks, form submissions)
+- E-commerce events (product views, purchases)
+- Content interactions (article reads, video plays)
+- Feature usage
+
+### Screen Tracking
+
+Track screen views to understand user navigation:
+
+```typescript
+import { Zixflow } from 'zixflow-reactnative';
+
+// Track screen view
+Zixflow.screen('HomeScreen');
+
+// Track screen with properties
+Zixflow.screen('ProductDetailScreen', {
+  product_id: '12345',
+  category: 'electronics'
+});
+```
+
+**Automatic screen tracking** with React Navigation:
+
+```typescript
+import { NavigationContainer, NavigationContainerRef } from '@react-navigation/native';
+import { Zixflow } from 'zixflow-reactnative';
+import React, { useRef } from 'react';
+
+export default function App() {
+  const navigationRef = useRef<NavigationContainerRef>(null);
+  const routeNameRef = useRef<string>();
+
+  return (
+    <NavigationContainer
+      ref={navigationRef}
+      onReady={() => {
+        routeNameRef.current = navigationRef.current?.getCurrentRoute()?.name;
+      }}
+      onStateChange={async () => {
+        const previousRouteName = routeNameRef.current;
+        const currentRouteName = navigationRef.current?.getCurrentRoute()?.name;
+
+        if (previousRouteName !== currentRouteName && currentRouteName) {
+          // Track screen change
+          Zixflow.screen(currentRouteName);
+        }
+
+        // Save current route name
+        routeNameRef.current = currentRouteName;
+      }}
+    >
+      {/* Your navigation setup */}
+    </NavigationContainer>
+  );
+}
+```
+
+### User Profile Attributes
+
+Set custom attributes on user profiles:
+
+```typescript
+import { Zixflow } from 'zixflow-reactnative';
+
+// Set profile attributes
+Zixflow.setProfileAttributes({
+  plan: 'premium',
+  subscription_status: 'active',
+  last_login: new Date().toISOString(),
+  preferences: {
+    newsletter: true,
+    notifications: true
+  }
+});
+```
+
+### Device Attributes
+
+Set custom attributes on the current device:
+
+```typescript
+import { Zixflow } from 'zixflow-reactnative';
+
+// Set device attributes
+Zixflow.setDeviceAttributes({
+  app_version: '2.1.0',
+  build_number: '421',
+  theme: 'dark',
+  language_preference: 'en-US'
+});
+```
+
+### Clearing User Identity
+
+Clear user identity when users log out:
+
+```typescript
+import { Zixflow } from 'zixflow-reactnative';
+
+// Clear identify on logout
+const handleLogout = async () => {
+  // Clear Zixflow identity
+  Zixflow.clearIdentify();
+
+  // Perform other logout actions
+  // ...
+};
+```
+
+---
+
+## Push Notifications
+
+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:
+
+1. **Configure push credentials in Zixflow dashboard** - Add APNs certificates or FCM Server Key
+2. **Complete iOS/Android native setup** - Ensure native dependencies are installed
+3. **Device tokens must be associated with users** - Call `identify()` before sending notifications
+
+**Important Limitation**: The Zixflow React Native SDK currently supports deep links and images in push notifications. Custom action buttons require additional native code.
+
+---
+
+### Platform-Specific Requirements
+
+#### iOS Requirements
+
+- **APNs or FCM**: Choose either Apple Push Notification service or Firebase Cloud Messaging
+- **Xcode Capabilities**: Push Notifications and Background Modes
+- **Notification Service Extension**: Required for rich push (images, videos)
+- **Physical Device**: iOS Simulator cannot receive push notifications
+
+#### Android Requirements
+
+- **Firebase Project**: Required for FCM integration
+- **google-services.json**: Must be in `android/app/` directory
+- **Minimum API Level 24**: Android 7.0 or higher
+- **POST_NOTIFICATIONS Permission**: Required for Android 13+ (API 33+)
+
+---
+
+### iOS Setup
+
+You can use either **APNs (Apple Push Notification service)** or **FCM (Firebase Cloud Messaging)** on iOS.
+
+#### Step 1: Enable Push Capabilities in Xcode
+
+1. Open your project's `.xcworkspace` file in Xcode
+2. Select your app target
+3. Go to **Signing & Capabilities** tab
+4. Click **+ Capability** → Add **Push Notifications**
+5. Click **+ Capability** → Add **Background Modes**
+6. Enable **Remote notifications** under Background Modes
+
+#### Step 2: Choose APNs or FCM
+
+**Option A: APNs (Recommended for iOS-only apps)**
+
+Update your `ios/Podfile`:
+
+```ruby
+require_relative '../node_modules/react-native/scripts/react_native_pods'
+require_relative '../node_modules/@react-native-community/cli-platform-ios/native_modules'
+
+platform :ios, '13.0'
+
+target 'YourApp' do
+  config = use_native_modules!
+
+  use_react_native!(:path => config[:reactNativePath])
+
+  # Add Zixflow with APNs support
+  pod 'zixflow-reactnative/apn', :path => '../node_modules/zixflow-reactnative'
+
+  # Your other dependencies...
+end
+```
+
+**Option B: FCM (For cross-platform Firebase apps)**
+
+Update your `ios/Podfile` with static linkage:
+
+```ruby
+require_relative '../node_modules/react-native/scripts/react_native_pods'
+require_relative '../node_modules/@react-native-community/cli-platform-ios/native_modules'
+
+platform :ios, '13.0'
+
+# Required for FCM
+use_frameworks! :linkage => :static
+
+target 'YourApp' do
+  config = use_native_modules!
+
+  use_react_native!(:path => config[:reactNativePath])
+
+  # Add Zixflow with FCM support
+  pod 'zixflow-reactnative/fcm', :path => '../node_modules/zixflow-reactnative'
+
+  # Your other dependencies...
+end
+```
+
+**Install dependencies:**
+
+```bash
+cd ios
+pod install
+cd ..
+```
+
+#### Step 3: Configure AppDelegate (Swift - Recommended)
+
+For modern Swift-based React Native apps with APNs:
+
+**AppDelegate.swift:**
+
+```swift
+import UIKit
+import ZixflowMessagingPushAPN
+
+@main
+class AppDelegateWithZixflowIntegration: ZixflowAppDelegateWrapper<AppDelegate> {}
+
+class AppDelegate: NSObject, UIApplicationDelegate {
+
+  func application(
+    _ application: UIApplication,
+    didFinishLaunchingWithOptions launchOptions: [UIApplication.LaunchOptionsKey: Any]?
+  ) -> Bool {
+    // Set notification delegate
+    UNUserNotificationCenter.current().delegate = self
+
+    // Initialize Zixflow push messaging (APNs)
+    MessagingPushAPN.initialize(
+      withConfig: MessagingPushConfigBuilder()
+        .build()
+    )
+
+    return true
+  }
+}
+
+extension AppDelegate: UNUserNotificationCenterDelegate {
+  // Show notifications when app is in foreground
+  func userNotificationCenter(
+    _ center: UNUserNotificationCenter,
+    willPresent notification: UNNotification,
+    withCompletionHandler completionHandler: @escaping (UNNotificationPresentationOptions) -> Void
+  ) {
+    completionHandler([.banner, .list, .badge, .sound])
+  }
+}
+```
+
+**For FCM**, import `ZixflowMessagingPushFCM` instead:
+
+```swift
+import ZixflowMessagingPushFCM
+
+// Initialize with FCM
+MessagingPushFCM.initialize(
+  withConfig: MessagingPushConfigBuilder()
+    .build()
+)
+```
+
+#### Step 4: Configure AppDelegate (Objective-C)
+
+If your React Native app uses Objective-C, create a Swift bridge:
+
+**Create `MyAppPushNotificationsHandler.swift`:**
+
+```swift
+import Foundation
+import ZixflowMessagingPushAPN
+
+@objc
+public class MyAppPushNotificationsHandler: NSObject {
+
+  @objc(setupZixflowClickHandling)
+  public func setupZixflowClickHandling() {
+    MessagingPushAPN.initialize(
+      withConfig: MessagingPushConfigBuilder().build()
+    )
+  }
+
+  @objc(application:deviceToken:)
+  public func application(
+    _ application: UIApplication,
+    didRegisterForRemoteNotificationsWithDeviceToken deviceToken: Data
+  ) {
+    MessagingPush.shared.application(
+      application,
+      didRegisterForRemoteNotificationsWithDeviceToken: deviceToken
+    )
+  }
+
+  @objc(application:error:)
+  public func application(
+    _ application: UIApplication,
+    didFailToRegisterForRemoteNotificationsWithError error: Error
+  ) {
+    MessagingPush.shared.application(
+      application,
+      didFailToRegisterForRemoteNotificationsWithError: error
+    )
+  }
+}
+```
+
+**Update `AppDelegate.mm`:**
+
+```objc
+#import "YourApp-Swift.h"
+
+@implementation AppDelegate
+
+MyAppPushNotificationsHandler* pnHandlerObj;
+
+- (BOOL)application:(UIApplication *)application
+    didFinishLaunchingWithOptions:(NSDictionary *)launchOptions {
+  // ... existing initialization code ...
+
+  // Register for remote notifications
+  [application registerForRemoteNotifications];
+
+  // Initialize push handling
+  pnHandlerObj = [[MyAppPushNotificationsHandler alloc] init];
+  [pnHandlerObj setupZixflowClickHandling];
+
+  return YES;
+}
+
+- (void)application:(UIApplication *)application
+    didRegisterForRemoteNotificationsWithDeviceToken:(NSData *)deviceToken {
+  [pnHandlerObj application:application deviceToken:deviceToken];
+}
+
+- (void)application:(UIApplication *)application
+    didFailToRegisterForRemoteNotificationsWithError:(NSError *)error {
+  [pnHandlerObj application:application error:error];
+}
+
+@end
+```
+
+#### Step 5: Rich Push with Notification Service Extension
+
+To support rich push notifications (images, videos, GIFs), add a Notification Service Extension:
+
+**1. Create Notification Service Extension:**
+
+1. In Xcode: **File** → **New** → **Target**
+2. Select **Notification Service Extension**
+3. Name it `NotificationServiceExtension`
+4. Click **Finish** (activate scheme when prompted)
+
+**2. Add Zixflow to Extension:**
+
+Update your `ios/Podfile` to include the extension:
+
+```ruby
+# Main app target
+target 'YourApp' do
+  # ... existing configuration ...
+  pod 'zixflow-reactnative/apn', :path => '../node_modules/zixflow-reactnative'
+end
+
+# Notification Service Extension target
+target 'NotificationServiceExtension' do
+  pod 'zixflow-reactnative-richpush/apn', :path => '../node_modules/zixflow-reactnative'
+end
+```
+
+For FCM:
+
+```ruby
+target 'NotificationServiceExtension' do
+  pod 'zixflow-reactnative-richpush/fcm', :path => '../node_modules/zixflow-reactnative'
+end
+```
+
+**3. Install dependencies:**
+
+```bash
+cd ios
+pod install
+cd ..
+```
+
+**4. Update `NotificationService.swift`:**
+
+```swift
+import UserNotifications
+import ZixflowMessagingPushAPN
+
+class NotificationService: UNNotificationServiceExtension {
+  var contentHandler: ((UNNotificationContent) -> Void)?
+  var bestAttemptContent: UNMutableNotificationContent?
+
+  override func didReceive(
+    _ request: UNNotificationRequest,
+    withContentHandler contentHandler: @escaping (UNNotificationContent) -> Void
+  ) {
+    self.contentHandler = contentHandler
+    bestAttemptContent = (request.content.mutableCopy() as? UNMutableNotificationContent)
+
+    // Initialize SDK for extension
+    MessagingPushAPN.initializeForExtension(
+      withConfig: MessagingPushConfigBuilder(apiKey: "YOUR_API_KEY")
+                .build()
+    )
+
+    if let bestAttemptContent = bestAttemptContent {
+      // Let Zixflow handle rich push and track delivery
+      MessagingPush.shared.didReceive(request, withContentHandler: contentHandler)
+    }
+  }
+
+  override func serviceExtensionTimeWillExpire() {
+    // Called when extension is about to be terminated
+    MessagingPush.shared.serviceExtensionTimeWillExpire()
+
+    if let contentHandler = contentHandler,
+       let bestAttemptContent = bestAttemptContent {
+      contentHandler(bestAttemptContent)
+    }
+  }
+}
+```
+
+**Important:** Replace `"YOUR_API_KEY"` with your actual API key.
+
+---
+
+### Android Setup
+
+Android push notifications use Firebase Cloud Messaging (FCM).
+
+#### Step 1: Add Firebase to Your Project
+
+1. Go to [Firebase Console](https://console.firebase.google.com/)
+2. Add your Android app to Firebase project
+3. Download `google-services.json`
+4. Place `google-services.json` in `android/app/` directory
+
+#### Step 2: Configure Gradle
+
+**Project-level `android/build.gradle`:**
+
+```gradle
+buildscript {
+    ext {
+        minSdkVersion = 24
+        compileSdkVersion = 34
+        targetSdkVersion = 34
+    }
+
+    dependencies {
+        classpath 'com.google.gms:google-services:4.4.2'
+    }
+}
+
+allprojects {
+    repositories {
+        google()
+        mavenCentral()
+    }
+}
+```
+
+**App-level `android/app/build.gradle`:**
+
+```gradle
+apply plugin: 'com.android.application'
+apply plugin: 'com.google.gms.google-services'  // Add this line
+
+android {
+    // ... existing configuration ...
+}
+
+dependencies {
+    // React Native auto-linking handles Zixflow dependencies
+    // ... your other dependencies ...
+}
+```
+
+#### Step 3: Add Permissions
+
+Add to `android/app/src/main/AndroidManifest.xml`:
+
+```xml
+<manifest xmlns:android="http://schemas.android.com/apk/res/android">
+
+    <!-- Required for push notifications -->
+    <uses-permission android:name="android.permission.INTERNET" />
+
+    <!-- Required for Android 13+ (API 33+) -->
+    <uses-permission android:name="android.permission.POST_NOTIFICATIONS" />
+
+    <application>
+        <!-- Your app configuration -->
+    </application>
+</manifest>
+```
+
+#### Step 4: Configure Notification Icon and Color (Optional)
+
+Add to `android/app/src/main/AndroidManifest.xml` inside `<application>` tag:
+
+```xml
+<application>
+    <!-- Default notification icon (white, transparent background) -->
+    <meta-data
+        android:name="com.google.firebase.messaging.default_notification_icon"
+        android:resource="@drawable/ic_notification" />
+
+    <!-- Default notification color (accent color) -->
+    <meta-data
+        android:name="com.google.firebase.messaging.default_notification_color"
+        android:resource="@color/notification_color" />
+</application>
+```
+
+---
+
+### React Native Integration
+
+#### Step 1: Initialize SDK
+
+Initialize the Zixflow SDK in your `App.tsx`:
+
+```typescript
+import React, { useEffect } from 'react';
+import { Zixflow, ZixflowConfig, ZixflowLogLevel } from 'zixflow-reactnative';
+
+export default function App() {
+  useEffect(() => {
+    // Configure the SDK
+    const config: ZixflowConfig = {
+      apiKey: 'YOUR_API_KEY',
+      logLevel: ZixflowLogLevel.debug,
+      inApp: {
+              },
+      autoTrackDeviceAttributes: true,
+      trackApplicationLifecycleEvents: true,
+    };
+
+    // Initialize the SDK
+    Zixflow.initialize(config);
+
+    console.log('Zixflow SDK initialized');
+  }, []);
+
+  return (
+    // Your app UI
+  );
+}
+```
+
+#### Step 2: Request Push Permission
+
+Request permission to send push notifications:
+
+```typescript
+import React, { useState } from 'react';
+import { Button, Alert } from 'react-native';
+import { Zixflow, ZixflowPushPermissionStatus } from 'zixflow-reactnative';
+
+export default function PushPermissionButton() {
+  const [permissionStatus, setPermissionStatus] = useState<ZixflowPushPermissionStatus | null>(null);
+
+  const requestPushPermission = async () => {
+    try {
+      const permission = await Zixflow.pushMessaging.showPromptForPushNotifications({
+        ios: {
+          sound: true,
+          badge: true,
+          alert: true,
+        },
+      });
+
+      setPermissionStatus(permission);
+
+      switch (permission) {
+        case ZixflowPushPermissionStatus.Granted:
+          Alert.alert('Success', 'Push notifications enabled!');
+          console.log('Push notifications enabled');
+          break;
+
+        case ZixflowPushPermissionStatus.Denied:
+          Alert.alert('Denied', 'Push notification permission was denied');
+          console.log('Push notifications denied');
+          break;
+
+        case ZixflowPushPermissionStatus.NotDetermined:
+          // iOS only: permission not yet asked
+          console.log('Push notification permission not determined');
+          break;
+      }
+    } catch (error) {
+      console.error('Failed to request push permission:', error);
+    }
+  };
+
+  return (
+    <Button
+      title="Enable Push Notifications"
+      onPress={requestPushPermission}
+    />
+  );
+}
+```
+
+**Permission Options (iOS)**:
+
+| Option | Type | Description |
+|--------|------|-------------|
+| `sound` | boolean | Enable notification sounds |
+| `badge` | boolean | Enable app badge updates |
+| `alert` | boolean | Show notification alerts |
+
+#### Step 3: Check Permission Status
+
+Check current push permission status:
+
+```typescript
+import { Zixflow, ZixflowPushPermissionStatus } from 'zixflow-reactnative';
+
+const checkPushPermission = async () => {
+  try {
+    const status = await Zixflow.pushMessaging.getPushPermissionStatus();
+
+    console.log('Push permission status:', status);
+
+    if (status === ZixflowPushPermissionStatus.Granted) {
+      console.log('Push notifications are enabled');
+    } else if (status === ZixflowPushPermissionStatus.Denied) {
+      console.log('Push notifications are disabled');
+    } else {
+      console.log('Push permission not determined');
+    }
+  } catch (error) {
+    console.error('Failed to get push permission status:', error);
+  }
+};
+```
+
+#### Step 4: Identify Users
+
+**Critical**: Device tokens must be associated with a user before push notifications can be delivered.
+
+```typescript
+import { Zixflow } from 'zixflow-reactnative';
+
+// Identify user when they log in
+const handleLogin = async (userId: string, userEmail: string) => {
+  try {
+    // Identify user with Zixflow
+    Zixflow.identify({
+      userId: userId,
+      traits: {
+        email: userEmail,
+        firstName: 'John',
+        lastName: 'Doe',
+        plan: 'premium',
+      },
+    });
+
+    console.log('User identified:', userId);
+  } catch (error) {
+    console.error('Failed to identify user:', error);
+  }
+};
+```
+
+**Important Notes:**
+- When users start the app, they automatically generate a device token
+- This token links to their Zixflow profile when you call `identify()`
+- This ensures notifications are delivered to the correct user
+
+#### Step 5: Get Device Token
+
+Retrieve the registered device token:
+
+```typescript
+import { Zixflow } from 'zixflow-reactnative';
+
+const getDeviceToken = async () => {
+  try {
+    const token = await Zixflow.pushMessaging.getRegisteredDeviceToken();
+    console.log('Device token:', token);
+    return token;
+  } catch (error) {
+    console.error('Failed to get device token:', error);
+    return null;
+  }
+};
+```
+
+---
+
+### Deep Links and Navigation
+
+Handle deep links from push notifications:
+
+#### Setup Deep Linking
+
+**1. Configure Deep Links (iOS):**
+
+Add to `ios/YourApp/Info.plist`:
+
+```xml
+<key>CFBundleURLTypes</key>
+<array>
+  <dict>
+    <key>CFBundleURLSchemes</key>
+    <array>
+      <string>yourapp</string>
+    </array>
+  </dict>
+</array>
+```
+
+**2. Configure Deep Links (Android):**
+
+Add to `android/app/src/main/AndroidManifest.xml`:
+
+```xml
+<activity android:name=".MainActivity">
+  <!-- Existing intent filter -->
+
+  <!-- Deep link intent filter -->
+  <intent-filter>
+    <action android:name="android.intent.action.VIEW" />
+    <category android:name="android.intent.category.DEFAULT" />
+    <category android:name="android.intent.category.BROWSABLE" />
+
+    <data
+      android:scheme="yourapp"
+      android:host="*" />
+  </intent-filter>
+
+  <!-- Universal Links (optional) -->
+  <intent-filter android:autoVerify="true">
+    <action android:name="android.intent.action.VIEW" />
+    <category android:name="android.intent.category.DEFAULT" />
+    <category android:name="android.intent.category.BROWSABLE" />
+
+    <data
+      android:scheme="https"
+      android:host="yourapp.com" />
+  </intent-filter>
+</activity>
+```
+
+#### Handle Deep Links in React Native
+
+Use React Navigation's linking configuration:
+
+```typescript
+import React from 'react';
+import { NavigationContainer } from '@react-navigation/native';
+import { createNativeStackNavigator } from '@react-navigation/native-stack';
+import { Linking } from 'react-native';
+
+const Stack = createNativeStackNavigator();
+
+const linking = {
+  prefixes: ['yourapp://', 'https://yourapp.com'],
+  config: {
+    screens: {
+      Home: 'home',
+      Product: 'product/:id',
+      Profile: 'profile',
+    },
+  },
+};
+
+export default function App() {
+  return (
+    <NavigationContainer linking={linking}>
+      <Stack.Navigator>
+        <Stack.Screen name="Home" component={HomeScreen} />
+        <Stack.Screen name="Product" component={ProductScreen} />
+        <Stack.Screen name="Profile" component={ProfileScreen} />
+      </Stack.Navigator>
+    </NavigationContainer>
+  );
+}
+```
+
+---
+
+### Rich Push Notification Payloads
+
+The Zixflow SDK automatically handles rich push notifications. Here's how to structure payloads:
+
+#### iOS APNs Payload
+
+```json
+{
+  "aps": {
+    "mutable-content": 1,
+    "alert": {
+      "title": "New Product Available",
+      "body": "Check out our latest premium features"
+    },
+    "badge": 1,
+    "sound": "default"
+  },
+  "Zixflow": {
+    "push": {
+      "link": "yourapp://product/123",
+      "image": "https://example.com/product-image.jpg"
+    }
+  }
+}
+```
+
+#### iOS FCM Payload
+
+```json
+{
+  "message": {
+    "apns": {
+      "payload": {
+        "aps": {
+          "mutable-content": 1,
+          "alert": {
+            "title": "Special Offer",
+            "body": "Limited time discount!"
+          }
+        },
+        "Zixflow": {
+          "push": {
+            "link": "https://yourapp.com/offers",
+            "image": "https://example.com/offer.png"
+          }
+        }
+      },
+      "headers": {
+        "apns-priority": 10
+      }
+    }
+  }
+}
+```
+
+#### Android FCM Payload
+
+```json
+{
+  "message": {
+    "data": {
+      "title": "Order Shipped",
+      "body": "Your order is on the way!",
+      "image": "https://example.com/shipping.jpg",
+      "link": "yourapp://orders/456"
+    }
+  }
+}
+```
+
+---
+
+### Testing Push Notifications
+
+#### 1. Verify Device Token Registration
+
+Check if device token is registered:
+
+```typescript
+const verifyPushSetup = async () => {
+  try {
+    const token = await Zixflow.pushMessaging.getRegisteredDeviceToken();
+    const status = await Zixflow.pushMessaging.getPushPermissionStatus();
+
+    console.log('Device token:', token);
+    console.log('Permission status:', status);
+
+    if (token && status === ZixflowPushPermissionStatus.Granted) {
+      console.log('✓ Push notifications ready');
+    } else {
+      console.log('✗ Push setup incomplete');
+    }
+  } catch (error) {
+    console.error('Push verification failed:', error);
+  }
+};
+```
+
+#### 2. Enable Debug Logging
+
+Set log level to debug during development:
+
+```typescript
+const config: ZixflowConfig = {
+  apiKey: 'YOUR_API_KEY',
+  logLevel: ZixflowLogLevel.debug,  // Verbose logging
+};
+
+Zixflow.initialize(config);
+```
+
+#### 3. Test on Physical Devices
+
+**iOS:**
+- Push notifications **do not work** on iOS Simulator
+- Must use physical iOS device
+- Ensure APNs certificate is configured in Zixflow dashboard
+
+**Android:**
+- Emulator works if Google Play Services installed
+- Physical device always recommended
+- Ensure FCM Server Key is configured in Zixflow dashboard
+
+#### 4. Send Test Push from Zixflow
+
+1. Log into Zixflow dashboard
+2. Navigate to **Messaging** → **Push Notifications**
+3. Create test push notification
+4. Send to specific user (using `userId` from `identify()`)
+
+---
+
+### Troubleshooting
+
+#### iOS Push Not Received
+
+**Symptoms:** Push sent but not delivered on iOS
+
+**Solutions:**
+1. Verify Push Notifications capability enabled in Xcode
+2. Check APNs certificate uploaded to Zixflow dashboard
+3. Ensure testing on physical device (not simulator)
+4. Verify user identified: `Zixflow.identify({ userId: ... })`
+5. Check permission granted: `getPushPermissionStatus()`
+6. Review logs for errors
+
+#### Android Push Not Received
+
+**Symptoms:** Push sent but not delivered on Android
+
+**Solutions:**
+1. Verify `google-services.json` in `android/app/` directory
+2. Check FCM Server Key in Zixflow dashboard
+3. Ensure POST_NOTIFICATIONS permission granted (Android 13+)
+4. Verify Google Services plugin applied
+5. Check device token registered
+6. Review logs for errors
+
+#### Rich Push Not Working (Images)
+
+**Symptoms:** Images not loading in notifications
+
+**iOS Solutions:**
+1. Ensure Notification Service Extension properly configured
+2. Verify extension has correct dependencies in Podfile
+3. Check App Groups configuration (if using)
+4. Verify image URL is accessible
+5. Check extension logs for errors
+
+**Android Solutions:**
+1. Verify image URL is accessible from device
+2. Check internet connectivity
+3. Ensure image format is supported (JPEG, PNG, GIF)
+
+#### Permission Denied
+
+**Symptoms:** User denied push permission
+
+**Solutions:**
+1. Explain value before requesting permission
+2. Guide users to Settings to enable manually
+3. Show in-app message explaining benefits
+4. Request permission at appropriate time (after user engagement)
+
+#### Device Token Not Registered
+
+**Symptoms:** `getRegisteredDeviceToken()` returns empty or fails
+
+**Solutions:**
+1. Verify SDK initialized before calling
+2. Check permission granted
+3. Ensure identify() called to associate token
+4. Review native logs for errors
+5. Rebuild app and retry
+
+---
+
+### Best Practices
+
+1. **Request permission thoughtfully** - Explain value before asking
+2. **Identify users immediately** after authentication
+3. **Test on physical devices** - Simulators have limitations
+4. **Use rich push** - Images increase engagement
+5. **Handle deep links** - Provide seamless navigation
+6. **Monitor metrics** - Track delivery and open rates
+7. **Enable debug logging** - During development only
+8. **Test both platforms** - iOS and Android behave differently
+9. **Clear identity on logout** - Call `clearIdentify()`
+10. **Keep credentials secure** - Never commit API keys to git
+
+---
+
+---
 
-The official Zixflow SDK for React Native enables you to integrate customer engagement features—like in-app messaging and push notifications—into your app. Track customer behavior, send targeted messages, and create personalized experiences.
+## Push Notification Tracking
 
-> 📖 Full documentation: [zixflow.com/docs/sdk/react-native](https://zixflow.com/docs/sdk/react-native/)
-> 🧪 Example apps: [see the `/example` directory](/example)
+### 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
 
-## About Zixflow
+### How Push Tracking Works
 
-Zixflow is a customer engagement platform built on proven Zixflow technology. This SDK is a customized fork of the Zixflow React Native SDK, optimized for use with the Zixflow platform.
+When Zixflow sends a push notification, it includes special tracking fields in the data payload:
 
-### Key Features
+| 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 |
+
+**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\":\"\"}]"
+}
+```
 
-- 📊 Customer identification and event tracking
-- 📲 Push notifications (iOS APN and Android FCM)
-- 💬 In-app messaging
-- 📍 Location tracking (optional)
-- 🎯 Personalized customer experiences
-- 📈 Analytics and customer data pipelines
-- 🔧 TypeScript support
-- ⚡ React Native New Architecture (TurboModules) support
+> **Note:** The SDK automatically handles most tracking for you when using the default push implementation. This section covers advanced customization scenarios.
 
 ---
 
-## Installation
+### Tracking Events
 
-```bash
-npm install zixflow-reactnative
-```
+#### 1. Delivery Confirmed
 
-or
+**When to track:** The moment the push payload arrives on the device
 
-```bash
-yarn add zixflow-reactnative
+**SDK method:** `Zixflow.trackMetric({ deliveryID, deviceToken, event: MetricEvent.delivered })`
+
+**Implementation:**
+
+```typescript
+import messaging from '@react-native-firebase/messaging';
+import { Zixflow, MetricEvent } from 'zixflow-reactnative';
+
+// 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,
+      });
+    }
+  });
+
+  return unsubscribe;
+}, []);
 ```
 
+> **Important:** The Zixflow SDK automatically tracks delivery. Manual tracking is only needed for custom implementations.
+
 ---
 
-## Quick Start
+#### 2. Notification Opened
 
-### SDK Initialization
+**When to track:** When the user taps the notification banner
+
+**SDK method:** `Zixflow.trackMetric({ deliveryID, deviceToken, event: MetricEvent.opened })`
 
-Here's a simplified example showing how to initialize the SDK to enable mobile features:
+**Implementation:**
 
-```ts
-import {
-  Zixflow,
-  ZixflowConfig,
-  ZixflowLogLevel,
-} from 'zixflow-reactnative';
+```typescript
+import messaging from '@react-native-firebase/messaging';
+import { Zixflow, MetricEvent } from 'zixflow-reactnative';
 
+// Background / quit tap
 useEffect(() => {
-  const config: ZixflowConfig = {
-    cdpApiKey: 'your-api-key', // Required
-    migrationSiteId: 'your-site-id', // Optional, for migrating from older SDKs
-    logLevel: ZixflowLogLevel.Debug,
-    trackApplicationLifecycleEvents: true,
-    inApp: {
-      siteId: 'your-site-id', // Required for in-app messaging
-    },
-    push: {
-      android: {
-        pushClickBehavior: 'ActivityPreventRestart', // Optional
-      },
-    },
-  };
+  const unsubscribe = messaging().onNotificationOpenedApp(async (remoteMessage) => {
+    trackOpened(remoteMessage.data);
+    handleDeeplink(remoteMessage.data?.deeplink_url);
+  });
+
+  return unsubscribe;
+}, []);
 
-  Zixflow.initialize(config);
+// Terminated tap
+useEffect(() => {
+  messaging()
+    .getInitialNotification()
+    .then((remoteMessage) => {
+      if (remoteMessage) {
+        trackOpened(remoteMessage.data);
+        handleDeeplink(remoteMessage.data?.deeplink_url);
+      }
+    });
 }, []);
+
+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,
+    });
+  }
+};
 ```
 
-> 🔑 For help finding your credentials, check out the [Quick Start Guide](https://zixflow.com/docs/sdk/react-native/quick-start-guide/).
+> **Note:** The SDK automatically tracks opens when using the default push implementation.
 
 ---
 
-## Core Features
+#### 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 [];
+  }
+};
+```
 
-### 👤 Identify Users
+**Action button properties:**
 
-Associate events and devices with customer profiles:
+| 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 |
 
-```ts
-Zixflow.identify({
-  userId: 'user123',
-  traits: {
-    email: 'user@example.com',
-    firstName: 'John',
-    lastName: 'Doe',
-    plan: 'premium',
-  },
-});
-```
+---
 
-### 📊 Track Events
+### Action Buttons Format
 
-Track custom events to trigger messaging based on user behavior:
+The `action_buttons` field is a JSON-encoded string containing button definitions:
 
-```ts
-Zixflow.track('Product Viewed', {
-  productId: '12345',
-  productName: 'Awesome Product',
-  price: 49.99,
-  category: 'Electronics',
-});
+**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": "" }
+]
 ```
 
-### 📺 Screen Tracking
+**Parsing example:**
+
+```typescript
+const parseActionButtons = (raw: any): Array<{ name: string; deeplink: string }> => {
+  if (!raw) return [];
 
-Track screen views in your app:
+  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 [];
+  }
+};
 
-```ts
-Zixflow.screen('Product Details', {
-  productId: '12345',
-  category: 'Electronics',
+// Usage
+const buttons = parseActionButtons(remoteMessage.data?.action_buttons);
+buttons.forEach((btn, index) => {
+  console.log(`Button ${index}: ${btn.name} -> ${btn.deeplink}`);
 });
 ```
 
-### 🏷️ Set Profile Attributes
+**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)
 
-Update customer profile attributes:
+---
 
-```ts
-Zixflow.setProfileAttributes({
-  plan: 'enterprise',
-  lastSeenAt: Date.now(),
-  preferences: {
-    notifications: true,
-    newsletter: true,
-  },
-});
+### 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;
 ```
 
 ---
 
-## 📲 Push Notifications
+### Tracking Decision Flowchart
 
-This SDK supports rich push notifications using Firebase (for Android) and either Firebase or APNs (for iOS).
+```
+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
+```
 
-### Request Permission (iOS)
+---
 
-```ts
-const status = await Zixflow.pushMessaging.showPromptForPushNotifications();
-console.log('Push permission status:', status);
-```
+### Fallback for Non-Zixflow Push
 
-### Handle Push Notifications
+If a push notification doesn't contain `Zixflow-Delivery-ID` (sent from another source), the SDK automatically skips tracking.
 
-```ts
-// Track when user receives a notification
-Zixflow.pushMessaging.onMessageReceived((message) => {
-  console.log('Notification received:', message);
-});
+For custom analytics on non-Zixflow pushes, use a different event name:
 
-// Track when user clicks on a notification
-Zixflow.pushMessaging.onBackgroundMessageReceived((message) => {
-  console.log('Notification clicked:', message);
+```typescript
+// 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',
+  },
 });
 ```
 
-Follow our [push setup guide](https://zixflow.com/docs/sdk/react-native/push/) to configure your project for push.
+> **Important:** Push notification event names (`Push Notification Delivered`, `Push Notification Opened`, `Push Notification Action Clicked`) are reserved for Zixflow's delivery pipeline.
 
 ---
 
-## 💬 In-App Messaging
+### Testing Push Tracking
 
-Display in-app messages to your users:
+#### Verify Tracking Events
 
-```ts
-import { InAppMessageEvent, InAppMessageEventType } from 'zixflow-reactnative';
+Enable debug logging to see tracking events:
 
-// Register event listener
-Zixflow.inAppMessaging.registerEventsListener((event: InAppMessageEvent) => {
-  switch (event.eventType) {
-    case InAppMessageEventType.MessageShown:
-      console.log('In-app message shown:', event.message);
-      break;
-    case InAppMessageEventType.MessageClicked:
-      console.log('In-app message clicked:', event.message);
-      break;
-    case InAppMessageEventType.MessageDismissed:
-      console.log('In-app message dismissed:', event.message);
-      break;
-  }
-});
+```typescript
+const config: ZixflowConfig = {
+  apiKey: 'YOUR_API_KEY',
+  logLevel: 'debug',
+};
 
-// Dismiss message programmatically
-Zixflow.inAppMessaging.dismissMessage();
+await Zixflow.setup(config);
 ```
 
-### Inbox Messages
+Look for these log messages:
+- `[Zixflow] Push Notification Delivered tracked`
+- `[Zixflow] Push Notification Opened tracked`
+- `[Zixflow] Push Notification Action Clicked tracked`
 
-Manage inbox messages:
+#### Check Campaign Analytics
 
-```ts
-const inbox = Zixflow.inAppMessaging.inbox();
+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
 
-// Get all messages
-const messages = await inbox.getMessages();
+---
 
-// Mark message as read
-await inbox.markMessageOpened(messageId);
+## Location Tracking
 
-// Delete message
-await inbox.markMessageDeleted(messageId);
+Enable location tracking to send location-based messages:
 
-// Subscribe to inbox updates
-inbox.subscribeToMessages((messages) => {
-  console.log('Inbox updated:', messages);
-});
+```typescript
+import { Zixflow } from 'zixflow-reactnative';
+
+// Location tracking is configured via the native SDK
+// Make sure to request location permissions in your app
+
+// iOS: Add location permission keys to Info.plist
+// - NSLocationWhenInUseUsageDescription
+// - NSLocationAlwaysAndWhenInUseUsageDescription
+
+// Android: Add location permissions to AndroidManifest.xml
+// - ACCESS_FINE_LOCATION
+// - ACCESS_COARSE_LOCATION
 ```
 
----
+Request location permissions using a library like `react-native-permissions`:
 
-## 📍 Location Tracking
+```typescript
+import { request, PERMISSIONS, RESULTS } from 'react-native-permissions';
+import { Platform } from 'react-native';
 
-Track user location (optional feature):
+const requestLocationPermission = async () => {
+  const permission = Platform.select({
+    ios: PERMISSIONS.IOS.LOCATION_WHEN_IN_USE,
+    android: PERMISSIONS.ANDROID.ACCESS_FINE_LOCATION,
+  });
 
-```ts
-Zixflow.location.setLastKnownLocation(latitude, longitude);
-```
+  if (!permission) return;
+
+  const result = await request(permission);
 
-### iOS Location Setup
+  if (result === RESULTS.GRANTED) {
+    console.log('Location permission granted');
+  }
+};
+```
 
-**Important:** iOS requires location permission descriptions in `Info.plist`. Add these keys or location tracking will silently fail:
+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:
 
-```xml
-<key>NSLocationWhenInUseUsageDescription</key>
-<string>We need your location to provide personalized experiences</string>
-<key>NSLocationAlwaysUsageDescription</key>
-<string>We need your location to provide personalized experiences</string>
+```swift
+NativeZixflow.configureAcknowledgedSceneDeepLinkRouting()
 ```
 
-Add the location pod to your `ios/Podfile`:
-```ruby
-pod 'zixflow-reactnative/location', :path => '../node_modules/zixflow-reactnative'
+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
+const subscription = Zixflow.setDeepLinkHandler(async (url) => {
+  if (!canRouteInApp(url)) {
+    return false;
+  }
+
+  await routeInApp(url);
+  return true;
+});
+
+Zixflow.initialize(config);
 ```
 
-### Android Location Setup
+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.
 
-Enable location tracking in `android/gradle.properties`:
-```properties
-zixflow_location_enabled=true
+The existing `Linking` path remains available for backward compatibility. Keep
+`NativeZixflow.configureSceneDeepLinkRouting()` in your SceneDelegate, then signal readiness
+after registering the listener:
+
+```typescript
+const subscription = Linking.addEventListener('url', ({ url }) => {
+  // Route the URL in your app.
+});
+Zixflow.setDeepLinkRoutingReady();
 ```
 
+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.
+
+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.
+
+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.
+
+This integration applies after the host has adopted React Native's UIScene lifecycle; the plugin does not replace React Native's root application lifecycle.
+
+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.
+
 ---
 
-## Advanced Features
+## Geofence Tracking
 
-### Device Attributes
+Geofence is an optional module, off by default. Enabling it also enables the Location module, which geofence depends on.
 
-Set custom device attributes:
+Enable it at build time:
 
-```ts
-Zixflow.setDeviceAttributes({
-  deviceModel: 'iPhone 14 Pro',
-  appVersion: '2.1.0',
-  customAttribute: 'value',
-});
+```properties
+# android/gradle.properties
+zixflow_geofence_enabled=true
 ```
 
-### Register Device Token
+```ruby
+# ios/Podfile
+pod 'zixflow-reactnative', :subspecs => ['geofence']
+```
 
-Register a device token for push notifications:
+Then opt in by passing a `geofence` config to `initialize`:
 
-```ts
-Zixflow.registerDeviceToken('your-device-token');
+```typescript
+import { Zixflow, ZixflowGeofenceLocationMode } from 'zixflow-reactnative';
+
+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,
+  },
+});
 ```
 
-### Clear Identification
+Request location permissions the same way as for [Location Tracking](#location-tracking) above — geofence monitoring requires them and the SDK never requests permission itself.
 
-Clear the current user identification:
+With `MANUAL` location mode, trigger a refresh after permission is granted:
 
-```ts
-Zixflow.clearIdentify();
+```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.
+
 ---
 
-## Platform-Specific Setup
+## 🔴 Live Activities
 
-### iOS Setup
+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:
 
-1. Add pods to your `ios/Podfile`:
+```xml
+<key>NSSupportsLiveActivities</key>
+<true/>
+```
 
-```ruby
-pod 'zixflow-reactnative', :path => '../node_modules/zixflow-reactnative'
+**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 FCM push:
-pod 'zixflow-reactnative/fcm', :path => '../node_modules/zixflow-reactnative'
+For an AppDelegate host:
 
-# For APN push:
-pod 'zixflow-reactnative/apn', :path => '../node_modules/zixflow-reactnative'
+```swift
+import zixflow_reactnative
+import React
 
-# For location tracking:
-pod 'zixflow-reactnative/location', :path => '../node_modules/zixflow-reactnative'
+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)
+  }
+}
 ```
 
-2. Run `pod install` in the `ios` directory
+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.
 
-3. Follow the [iOS push setup guide](https://zixflow.com/docs/sdk/react-native/push/ios)
+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`:
 
-### Android Setup
+```swift
+import zixflow_reactnative
 
-#### Requirements
+reactNativeFactory?.startReactNative(
+  withModuleName: "YourApp",
+  in: window,
+  launchOptions: NativeLiveActivities.reactNativeLaunchOptions(from: connectionOptions)
+)
+```
 
-- **compileSdkVersion**: 36 or higher
-- **Android Gradle Plugin**: 8.9.1 or higher
-- **Gradle**: 8.11.1 or higher
-- **minSdkVersion**: 21 or higher
-- **Kotlin**: 1.9.25 or higher
+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`:
 
-#### Configuration
+```swift
+import zixflow_reactnative
 
-1. Update your `android/build.gradle`:
+func scene(_ scene: UIScene, openURLContexts URLContexts: Set<UIOpenURLContext>) {
+  for context in URLContexts {
+    NativeLiveActivities.handleAndRouteWidgetUrl(context.url)
+  }
+}
+```
 
-```gradle
-buildscript {
-    ext {
-        compileSdkVersion = 36
-        buildToolsVersion = "36.0.0"
-        minSdkVersion = 21
-        targetSdkVersion = 36
-    }
-    dependencies {
-        classpath("com.android.tools.build:gradle:8.9.1")
-    }
+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.
+
+Android needs no equivalent native step.
+
+For Expo Router, unwrap the URL once in the app's top-level `app/+native-intent.tsx` file:
+
+```typescript
+import { Zixflow } from 'zixflow-reactnative';
+
+export async function redirectSystemPath({ path }: { path: string }) {
+  return Zixflow.liveActivities.handleWidgetUrl(path);
 }
 ```
 
-2. Update `android/gradle/wrapper/gradle-wrapper.properties`:
+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.
 
-```properties
-distributionUrl=https\://services.gradle.org/distributions/gradle-8.11.1-all.zip
+---
+
+## Notification Inbox
+
+The Visual Notification Inbox renders received messages in a list the SDK owns the design of. Two components are available:
+
+- `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).
+
+```tsx
+import { NotificationInboxBellView, NotificationInboxView } from 'zixflow-reactnative';
+
+// 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')}
+/>
+
+// Or embed the message list directly in a screen of your own.
+<NotificationInboxView style={{ flex: 1 }} />
 ```
 
-3. Add Kotlin compiler flag in `android/app/build.gradle`:
+`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.
 
-```gradle
-android {
-    // ... other config
-}
+Remote branding styles the bell and list themselves (colors, icon); the host still owns layout and placement via `style`.
 
-tasks.withType(org.jetbrains.kotlin.gradle.tasks.KotlinCompile).all {
-    kotlinOptions {
-        freeCompilerArgs += ['-Xskip-metadata-version-check']
-    }
-}
+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'),
+    },
+  },
+});
 ```
 
-4. The SDK is automatically linked via autolinking
+Register a listener to observe inbox events (shown, opened, dismissed, and non-dismiss actions taken on a message):
 
-5. (Optional) Enable location tracking in `android/gradle.properties`:
+```typescript
+import { InboxEventType } from 'zixflow-reactnative';
 
-```properties
-zixflow_location_enabled=true
+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;
+  }
+});
+
+// Remove listener
+subscription.remove();
 ```
 
-6. Follow the [Android push setup guide](https://zixflow.com/docs/sdk/react-native/push/android)
+You can also fetch and manage inbox messages directly through `Zixflow.inAppMessaging.inbox()`:
 
----
+```typescript
+const inbox = Zixflow.inAppMessaging.inbox();
 
-## Configuration Options
+const messages = await inbox.getMessages();
 
-| Option | Type | Required | Description |
-|--------|------|----------|-------------|
-| `cdpApiKey` | `string` | ✅ | Your Zixflow API key |
-| `migrationSiteId` | `string` | ❌ | Site ID for migration from older SDKs |
-| `logLevel` | `ZixflowLogLevel` | ❌ | Logging verbosity (default: error) |
-| `trackApplicationLifecycleEvents` | `boolean` | ❌ | Auto-track app lifecycle events |
-| `inApp` | `object` | ❌ | In-app messaging configuration |
-| `push` | `object` | ❌ | Push notification configuration |
+inbox.markMessageOpened(message);
+inbox.markMessageDeleted(message);
+```
 
 ---
 
-## TypeScript Support
+## Advanced Configuration
+
+### Log Levels
 
-This SDK is written in TypeScript and includes full type definitions:
+Control SDK logging for debugging:
 
-```ts
-import type {
-  Zixflow,
-  ZixflowConfig,
-  ZixflowInAppMessaging,
-  ZixflowPushMessaging,
-  ZixflowLocation,
-  CustomAttributes,
-  IdentifyParams,
-  InAppMessage,
-  InboxMessage,
-} from 'zixflow-reactnative';
+```typescript
+import { Zixflow, ZixflowLogLevel } from 'zixflow-reactnative';
+
+const config = {
+  apiKey: 'YOUR_API_KEY',
+  logLevel: ZixflowLogLevel.debug,  // debug, info, error, none
+};
+
+Zixflow.initialize(config);
 ```
 
----
+**Log levels**:
+- `ZixflowLogLevel.debug` - Verbose logging (development)
+- `ZixflowLogLevel.info` - Informational messages
+- `ZixflowLogLevel.error` - Errors only
+- `ZixflowLogLevel.none` - No logging (production)
+
+### Auto-Tracking Options
 
-## Module APIs
+Configure automatic tracking features:
 
-Access specific SDK modules:
+```typescript
+import { Zixflow } from 'zixflow-reactnative';
 
-```ts
-// In-app messaging
-Zixflow.inAppMessaging.registerEventsListener(listener);
+const config = {
+  apiKey: 'YOUR_API_KEY',
 
-// Push messaging
-Zixflow.pushMessaging.showPromptForPushNotifications();
+  // Automatically track device attributes (OS, model, app version)
+  autoTrackDeviceAttributes: true,
 
-// Location tracking
-Zixflow.location.setLastKnownLocation(lat, lng);
+  // Automatically track app lifecycle events (open, close, background)
+  trackApplicationLifecycleEvents: true,
+
+  // Automatically track screens (requires integration)
+  autoTrackScreenViews: true,
+};
+
+Zixflow.initialize(config);
 ```
 
-Note: Due to JavaScript limitations, module properties return the internal implementation instances, but all functionality works as expected.
+### Custom API Hosts
+
+Override API endpoints for testing or custom infrastructure:
+
+```typescript
+import { Zixflow } from 'zixflow-reactnative';
+
+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);
+```
 
 ---
 
-## Example App
+## Example Applications
+
+The Zixflow React Native SDK includes example applications demonstrating best practices:
+
+### Sample App (APNs)
 
-Check out our comprehensive [example app](/example) that demonstrates:
+Location: `example/`
 
-- SDK initialization
-- User identification
+**Features**:
+- User identification and logout
 - Event tracking
-- Push notifications
-- In-app messaging
-- Location tracking
-- Inbox management
+- Screen tracking with React Navigation
+- Push notifications with APNs
+- In-app messaging with event listeners
+- Profile and device attributes
 
-To run the example app:
+**Running the example**:
 
 ```bash
+# Install dependencies
 cd example
 npm install
 
@@ -454,64 +2246,174 @@ npx react-native run-android
 
 ---
 
-## Troubleshooting
+## API Reference
 
-### Common Issues
+### Core SDK
 
-**Issue: Build fails with "Zixflow pod not found"**
-- Run `pod install` in your iOS directory
-- Make sure you're using the correct pod name: `zixflow-reactnative`
+#### `Zixflow.initialize(config: ZixflowConfig): void`
 
-**Issue: Push notifications not working**
-- Verify your Firebase configuration (Android) or APNs certificates (iOS)
-- Check that you've requested push permissions
-- Ensure you've registered the device token
+Initialize the SDK with configuration.
 
-**Issue: In-app messages not showing**
-- Verify you've configured `inApp.siteId` in the config
-- Check that you've registered an events listener
-- Ensure messages are targeted correctly in your Zixflow dashboard
+```typescript
+Zixflow.initialize({
+  apiKey: 'YOUR_API_KEY',
+});
+```
 
-For more help, see our [troubleshooting guide](https://zixflow.com/docs/sdk/react-native/troubleshooting/) or [open an issue](https://github.com/zixflow/zixflow-reactnative/issues).
+#### `Zixflow.identify(params: { userId: string; traits?: object }): void`
 
----
+Identify a user with optional traits.
 
-## Requirements
+```typescript
+Zixflow.identify({
+  userId: 'user-123',
+  traits: { email: 'user@example.com' }
+});
+```
 
-- React Native 0.70+
-- iOS 13+
-- Android API 21+ (Android 5.0 Lollipop)
-- Swift 5.3+
-- Kotlin 1.8+
+#### `Zixflow.clearIdentify(): void`
 
----
+Clear the current user's identity.
 
-## Contributing
+```typescript
+Zixflow.clearIdentify();
+```
 
-We welcome contributions! To get started:
+#### `Zixflow.track(name: string, properties?: object | Map<string, any>): void`
 
-1. Review our [example app](/example) to help with local development
-2. Follow our [Code of Conduct](CODE_OF_CONDUCT.md)
-3. Check out [DEVELOPMENT.md](DEVELOPMENT.md) for development guidelines
-4. Open issues or pull requests on [GitHub](https://github.com/zixflow/zixflow-reactnative)
+Track a custom event.
 
----
+```typescript
+Zixflow.track('button_clicked', { button_name: 'signup' });
+```
 
-## Support
+#### `Zixflow.screen(name: string, properties?: object): void`
 
-- 📚 [Documentation](https://zixflow.com/docs/sdk/react-native/)
-- 💬 [Community Forum](https://community.zixflow.com)
-- 🐛 [Issue Tracker](https://github.com/zixflow/zixflow-reactnative/issues)
-- 📧 Email: apps@zixflow.com
+Track a screen view.
 
----
+```typescript
+Zixflow.screen('HomeScreen');
+```
 
-## License
+#### `Zixflow.setProfileAttributes(attributes: object): void`
 
-[MIT](LICENSE)
+Set attributes on the user profile.
 
----
+```typescript
+Zixflow.setProfileAttributes({ plan: 'premium' });
+```
+
+#### `Zixflow.setDeviceAttributes(attributes: object): void`
+
+Set attributes on the current device.
+
+```typescript
+Zixflow.setDeviceAttributes({ app_version: '2.0.0' });
+```
+
+### Push Messaging
+
+#### `Zixflow.pushMessaging.showPromptForPushNotifications(options): Promise<ZixflowPushPermissionStatus>`
+
+Request push notification permission.
+
+```typescript
+const status = await Zixflow.pushMessaging.showPromptForPushNotifications({
+  ios: { sound: true, badge: true }
+});
+```
+
+### In-App Messaging
+
+#### `Zixflow.inAppMessaging.registerEventsListener(callback): EventSubscription`
+
+Register a listener for in-app message events.
+
+```typescript
+const listener = Zixflow.inAppMessaging.registerEventsListener((event) => {
+  console.log('In-app event:', event);
+});
+
+// Remove listener
+listener.remove();
+```
+
+#### `Zixflow.inAppMessaging.dismissMessage(): void`
+
+Dismiss the currently displayed in-app message.
+
+```typescript
+Zixflow.inAppMessaging.dismissMessage();
+```
+
+### Types
+
+#### `ZixflowConfig`
+
+Configuration object for SDK initialization.
+
+```typescript
+interface ZixflowConfig {
+  apiKey: string;
+  logLevel?: ZixflowLogLevel;
+  inApp?: {
+  };
+  autoTrackDeviceAttributes?: boolean;
+  trackApplicationLifecycleEvents?: boolean;
+  autoTrackScreenViews?: boolean;
+  trackingApiUrl?: string;
+}
+```
+
+#### `ZixflowLogLevel`
+
+Log level enum.
+
+```typescript
+enum ZixflowLogLevel {
+  none = 'none',
+  error = 'error',
+  info = 'info',
+  debug = 'debug'
+}
+```
+
+#### `ZixflowPushPermissionStatus`
+
+Push notification permission status.
+
+```typescript
+enum ZixflowPushPermissionStatus {
+  Granted = 'granted',
+  Denied = 'denied',
+  NotDetermined = 'notDetermined'
+}
+```
+
+#### `InAppMessageEventType`
 
-## Acknowledgments
+In-app message event types.
+
+```typescript
+enum InAppMessageEventType {
+  messageShown = 'messageShown',
+  messageDismissed = 'messageDismissed',
+  messageActionTaken = 'messageActionTaken',
+  errorWithMessage = 'errorWithMessage'
+}
+```
+
+#### `InAppMessageEvent`
+
+In-app message event object.
+
+```typescript
+interface InAppMessageEvent {
+  eventType: InAppMessageEventType;
+  deliveryId?: string;
+  messageId?: string;
+  actionName?: string;
+  actionValue?: string;
+}
+```
 
-This SDK is based on the Zixflow React Native SDK and maintains compatibility with the Zixflow platform while providing Zixflow-specific optimizations and branding.