zixflow-reactnative 1.1.1 → 1.1.3

package/README.md

@@ -1,451 +1,2049 @@
-<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. [In-App Messaging](#in-app-messaging)
+   - [Event Listeners](#event-listeners)
+   - [Message Events](#message-events)
+   - [Dismissing Messages](#dismissing-messages)
+10. [Location Tracking](#location-tracking)
+11. [Advanced Configuration](#advanced-configuration)
+    - [Region Settings](#region-settings)
+    - [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)
+
+---
 
-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.
+## Introduction
 
-> 📖 Full documentation: [zixflow.com/docs/sdk/react-native](https://zixflow.com/docs/sdk/react-native/)
-> 🧪 Example apps: [see the `/example` directory](/example)
+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.
 
 ---
 
-## About Zixflow
+## Requirements
+
+### React Native
 
-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.
+- **React Native**: 0.60.0 or higher
+- **React**: 16.8.0 or higher (for hooks support)
 
-### Key Features
+### iOS
 
-- 📊 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
+- **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
 
+### npm Installation
+
+Install the SDK using npm:
+
 ```bash
 npm install zixflow-reactnative
 ```
 
-or
+### 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 "ZixflowTrackingMigration", "~> 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
 
-### SDK Initialization
+### Basic Configuration
 
-Here's a simplified example showing how to initialize the SDK to enable mobile features:
+The SDK is configured using a `ZixflowConfig` object with several options:
 
-```ts
-import {
-  Zixflow,
-  ZixflowConfig,
-  ZixflowLogLevel,
-  ZixflowRegion,
-} from 'zixflow-reactnative';
+```typescript
+import { Zixflow, ZixflowConfig, ZixflowLogLevel } from 'zixflow-reactnative';
 
-useEffect(() => {
-  const config: ZixflowConfig = {
-    cdpApiKey: 'your-api-key', // Required
-    migrationSiteId: 'your-site-id', // Optional, for migrating from older SDKs
-    region: ZixflowRegion.US, // Or ZixflowRegion.EU
-    logLevel: ZixflowLogLevel.Debug,
-    trackApplicationLifecycleEvents: true,
-    inApp: {
-      siteId: 'your-site-id', // Required for in-app messaging
-    },
-    push: {
-      android: {
-        pushClickBehavior: 'ActivityPreventRestart', // Optional
+const config: ZixflowConfig = {
+  apiKey: 'YOUR_API_KEY',
+  logLevel: ZixflowLogLevel.debug,
+  inApp: {
       },
-    },
-  };
+  autoTrackDeviceAttributes: true,
+  trackApplicationLifecycleEvents: true,
+};
+```
 
-  Zixflow.initialize(config);
-}, []);
+**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
+  );
+}
 ```
 
-> 🔑 For help finding your credentials, check out the [Quick Start Guide](https://zixflow.com/docs/sdk/react-native/quick-start-guide/).
+> **Important**: Initialize the SDK as early as possible in your app's lifecycle, ideally in the root component's `useEffect`.
 
 ---
 
 ## Core Features
 
-### 👤 Identify Users
+### User Identification
+
+Identify users to track their behavior across sessions and devices:
 
-Associate events and devices with customer profiles:
+```typescript
+import { Zixflow } from 'zixflow-reactnative';
+
+// Identify user with ID only
+Zixflow.identify({
+  userId: 'user-123'
+});
 
-```ts
+// Identify user with traits
 Zixflow.identify({
-  userId: 'user123',
+  userId: 'user-123',
   traits: {
     email: 'user@example.com',
     firstName: 'John',
     lastName: 'Doe',
-    plan: 'premium',
-  },
+    plan: 'premium'
+  }
 });
 ```
 
-### 📊 Track Events
+**When to identify users**:
+- After successful login
+- When user information becomes available
+- After account creation
+
+### Event Tracking
 
-Track custom events to trigger messaging based on user behavior:
+Track custom events to understand user behavior:
 
-```ts
-Zixflow.track('Product Viewed', {
-  productId: '12345',
-  productName: 'Awesome Product',
-  price: 49.99,
-  category: 'Electronics',
+```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);
 ```
 
-### 📺 Screen Tracking
+**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 in your app:
+Track screen views to understand user navigation:
 
-```ts
-Zixflow.screen('Product Details', {
-  productId: '12345',
-  category: 'Electronics',
+```typescript
+import { Zixflow } from 'zixflow-reactnative';
+
+// Track screen view
+Zixflow.screen('HomeScreen');
+
+// Track screen with properties
+Zixflow.screen('ProductDetailScreen', {
+  product_id: '12345',
+  category: 'electronics'
 });
 ```
 
-### 🏷️ Set Profile Attributes
+**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
 
-Update customer profile attributes:
+Set custom attributes on user profiles:
 
-```ts
+```typescript
+import { Zixflow } from 'zixflow-reactnative';
+
+// Set profile attributes
 Zixflow.setProfileAttributes({
-  plan: 'enterprise',
-  lastSeenAt: Date.now(),
+  plan: 'premium',
+  subscription_status: 'active',
+  last_login: new Date().toISOString(),
   preferences: {
-    notifications: true,
     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).
+
+### 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+)
+
 ---
 
-## 📲 Push Notifications
+### 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
 
-This SDK supports rich push notifications using Firebase (for Android) and either Firebase or APNs (for iOS).
+#### Step 2: Choose APNs or FCM
 
-### Request Permission (iOS)
+**Option A: APNs (Recommended for iOS-only apps)**
 
-```ts
-const status = await Zixflow.pushMessaging.showPromptForPushNotifications();
-console.log('Push permission status:', status);
+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
 ```
 
-### Handle Push Notifications
+**Option B: FCM (For cross-platform Firebase apps)**
 
-```ts
-// Track when user receives a notification
-Zixflow.pushMessaging.onMessageReceived((message) => {
-  console.log('Notification received:', message);
-});
+Update your `ios/Podfile` with static linkage:
 
-// Track when user clicks on a notification
-Zixflow.pushMessaging.onBackgroundMessageReceived((message) => {
-  console.log('Notification clicked:', message);
-});
+```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
 ```
 
-Follow our [push setup guide](https://zixflow.com/docs/sdk/react-native/push/) to configure your project for push.
+**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> {}
 
-## 💬 In-App Messaging
+class AppDelegate: NSObject, UIApplicationDelegate {
 
-Display in-app messages to your users:
+  func application(
+    _ application: UIApplication,
+    didFinishLaunchingWithOptions launchOptions: [UIApplication.LaunchOptionsKey: Any]?
+  ) -> Bool {
+    // Set notification delegate
+    UNUserNotificationCenter.current().delegate = self
 
-```ts
-import { InAppMessageEvent, InAppMessageEventType } from 'zixflow-reactnative';
+    // Initialize Zixflow push messaging (APNs)
+    MessagingPushAPN.initialize(
+      withConfig: MessagingPushConfigBuilder()
+        .build()
+    )
 
-// 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;
+    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])
+  }
+}
+```
 
-// Dismiss message programmatically
-Zixflow.inAppMessaging.dismissMessage();
+**For FCM**, import `ZixflowMessagingPushFCM` instead:
+
+```swift
+import ZixflowMessagingPushFCM
+
+// Initialize with FCM
+MessagingPushFCM.initialize(
+  withConfig: MessagingPushConfigBuilder()
+    .build()
+)
 ```
 
-### Inbox Messages
+#### Step 4: Configure AppDelegate (Objective-C)
 
-Manage inbox messages:
+If your React Native app uses Objective-C, create a Swift bridge:
 
-```ts
-const inbox = Zixflow.inAppMessaging.inbox();
+**Create `MyAppPushNotificationsHandler.swift`:**
 
-// Get all messages
-const messages = await inbox.getMessages();
+```swift
+import Foundation
+import ZixflowMessagingPushAPN
 
-// Mark message as read
-await inbox.markMessageOpened(messageId);
+@objc
+public class MyAppPushNotificationsHandler: NSObject {
 
-// Delete message
-await inbox.markMessageDeleted(messageId);
+  @objc(setupZixflowClickHandling)
+  public func setupZixflowClickHandling() {
+    MessagingPushAPN.initialize(
+      withConfig: MessagingPushConfigBuilder().build()
+    )
+  }
 
-// Subscribe to inbox updates
-inbox.subscribeToMessages((messages) => {
-  console.log('Inbox updated:', messages);
-});
+  @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 ...
 
-## 📍 Location Tracking
+  // Register for remote notifications
+  [application registerForRemoteNotifications];
 
-Track user location (optional feature):
+  // Initialize push handling
+  pnHandlerObj = [[MyAppPushNotificationsHandler alloc] init];
+  [pnHandlerObj setupZixflowClickHandling];
 
-```ts
-Zixflow.location.setLastKnownLocation(latitude, longitude);
+  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
 
-## Advanced Features
+To support rich push notifications (images, videos, GIFs), add a Notification Service Extension:
 
-### Device Attributes
+**1. Create Notification Service Extension:**
 
-Set custom device attributes:
+1. In Xcode: **File** → **New** → **Target**
+2. Select **Notification Service Extension**
+3. Name it `NotificationServiceExtension`
+4. Click **Finish** (activate scheme when prompted)
 
-```ts
-Zixflow.setDeviceAttributes({
-  deviceModel: 'iPhone 14 Pro',
-  appVersion: '2.1.0',
-  customAttribute: 'value',
-});
+**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
 ```
 
-### Register Device Token
+For FCM:
+
+```ruby
+target 'NotificationServiceExtension' do
+  pod 'zixflow-reactnative-richpush/fcm', :path => '../node_modules/zixflow-reactnative'
+end
+```
 
-Register a device token for push notifications:
+**3. Install dependencies:**
 
-```ts
-Zixflow.registerDeviceToken('your-device-token');
+```bash
+cd ios
+pod install
+cd ..
 ```
 
-### Clear Identification
+**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)
+    }
+  }
 
-Clear the current user identification:
+  override func serviceExtensionTimeWillExpire() {
+    // Called when extension is about to be terminated
+    MessagingPush.shared.serviceExtensionTimeWillExpire()
 
-```ts
-Zixflow.clearIdentify();
+    if let contentHandler = contentHandler,
+       let bestAttemptContent = bestAttemptContent {
+      contentHandler(bestAttemptContent)
+    }
+  }
+}
 ```
 
+**Important:** Replace `"YOUR_API_KEY"` with your actual API key.
+
 ---
 
-## Platform-Specific Setup
+### Android Setup
 
-### iOS Setup
+Android push notifications use Firebase Cloud Messaging (FCM).
 
-1. Add pods to your `ios/Podfile`:
+#### Step 1: Add Firebase to Your Project
 
-```ruby
-pod 'zixflow-reactnative', :path => '../node_modules/zixflow-reactnative'
+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
 
-# For FCM push:
-pod 'zixflow-reactnative/fcm', :path => '../node_modules/zixflow-reactnative'
+#### Step 2: Configure Gradle
 
-# For APN push:
-pod 'zixflow-reactnative/apn', :path => '../node_modules/zixflow-reactnative'
+**Project-level `android/build.gradle`:**
 
-# For location tracking:
-pod 'zixflow-reactnative/location', :path => '../node_modules/zixflow-reactnative'
-```
+```gradle
+buildscript {
+    ext {
+        minSdkVersion = 24
+        compileSdkVersion = 34
+        targetSdkVersion = 34
+    }
 
-2. Run `pod install` in the `ios` directory
+    dependencies {
+        classpath 'com.google.gms:google-services:4.4.2'
+    }
+}
 
-3. Follow the [iOS push setup guide](https://zixflow.com/docs/sdk/react-native/push/ios)
+allprojects {
+    repositories {
+        google()
+        mavenCentral()
+    }
+}
+```
 
-### Android Setup
+**App-level `android/app/build.gradle`:**
 
-1. The SDK is automatically linked via autolinking
+```gradle
+apply plugin: 'com.android.application'
+apply plugin: 'com.google.gms.google-services'  // Add this line
 
-2. (Optional) Enable location tracking in `android/gradle.properties`:
+android {
+    // ... existing configuration ...
+}
 
-```properties
-zixflow_location_enabled=true
+dependencies {
+    // React Native auto-linking handles Zixflow dependencies
+    // ... your other dependencies ...
+}
 ```
 
-3. Follow the [Android push setup guide](https://zixflow.com/docs/sdk/react-native/push/android)
+#### Step 3: Add Permissions
 
----
+Add to `android/app/src/main/AndroidManifest.xml`:
 
-## Configuration Options
+```xml
+<manifest xmlns:android="http://schemas.android.com/apk/res/android">
 
-| Option | Type | Required | Description |
-|--------|------|----------|-------------|
-| `cdpApiKey` | `string` | ✅ | Your Zixflow API key |
-| `migrationSiteId` | `string` | ❌ | Site ID for migration from older SDKs |
-| `region` | `ZixflowRegion` | ❌ | US or EU region (default: US) |
-| `logLevel` | `ZixflowLogLevel` | ❌ | Logging verbosity (default: error) |
-| `trackApplicationLifecycleEvents` | `boolean` | ❌ | Auto-track app lifecycle events |
-| `inApp` | `object` | ❌ | In-app messaging configuration |
-| `push` | `object` | ❌ | Push notification configuration |
+    <!-- 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)
 
-## TypeScript Support
+Add to `android/app/src/main/AndroidManifest.xml` inside `<application>` tag:
 
-This SDK is written in TypeScript and includes full type definitions:
+```xml
+<application>
+    <!-- Default notification icon (white, transparent background) -->
+    <meta-data
+        android:name="com.google.firebase.messaging.default_notification_icon"
+        android:resource="@drawable/ic_notification" />
 
-```ts
-import type {
-  Zixflow,
-  ZixflowConfig,
-  ZixflowInAppMessaging,
-  ZixflowPushMessaging,
-  ZixflowLocation,
-  CustomAttributes,
-  IdentifyParams,
-  InAppMessage,
-  InboxMessage,
-} from 'zixflow-reactnative';
+    <!-- Default notification color (accent color) -->
+    <meta-data
+        android:name="com.google.firebase.messaging.default_notification_color"
+        android:resource="@color/notification_color" />
+</application>
 ```
 
 ---
 
-## Module APIs
+### React Native Integration
 
-Access specific SDK modules:
+#### Step 1: Initialize SDK
 
-```ts
-// In-app messaging
-Zixflow.inAppMessaging.registerEventsListener(listener);
+Initialize the Zixflow SDK in your `App.tsx`:
 
-// Push messaging
-Zixflow.pushMessaging.showPromptForPushNotifications();
+```typescript
+import React, { useEffect } from 'react';
+import { Zixflow, ZixflowConfig, ZixflowLogLevel } from 'zixflow-reactnative';
 
-// Location tracking
-Zixflow.location.setLastKnownLocation(lat, lng);
+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
+  );
+}
 ```
 
-Note: Due to JavaScript limitations, module properties return the internal implementation instances, but all functionality works as expected.
+#### 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}
+    />
+  );
+}
+```
 
-## Example App
+**Permission Options (iOS)**:
 
-Check out our comprehensive [example app](/example) that demonstrates:
+| Option | Type | Description |
+|--------|------|-------------|
+| `sound` | boolean | Enable notification sounds |
+| `badge` | boolean | Enable app badge updates |
+| `alert` | boolean | Show notification alerts |
 
-- SDK initialization
-- User identification
-- Event tracking
-- Push notifications
-- In-app messaging
-- Location tracking
-- Inbox management
+#### Step 3: Check Permission Status
 
-To run the example app:
+Check current push permission status:
 
-```bash
-cd example
-npm install
+```typescript
+import { Zixflow, ZixflowPushPermissionStatus } from 'zixflow-reactnative';
 
-# iOS
-cd ios && pod install && cd ..
-npx react-native run-ios
+const checkPushPermission = async () => {
+  try {
+    const status = await Zixflow.pushMessaging.getPushPermissionStatus();
 
-# Android
-npx react-native run-android
+    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
 
-## Troubleshooting
+**Critical**: Device tokens must be associated with a user before push notifications can be delivered.
 
-### Common Issues
+```typescript
+import { Zixflow } from 'zixflow-reactnative';
 
-**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`
+// 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',
+      },
+    });
 
-**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
+    console.log('User identified:', userId);
+  } catch (error) {
+    console.error('Failed to identify user:', error);
+  }
+};
+```
 
-**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
+**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
 
-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).
+#### Step 5: Get Device Token
 
----
+Retrieve the registered device token:
 
-## Requirements
+```typescript
+import { Zixflow } from 'zixflow-reactnative';
 
-- React Native 0.70+
-- iOS 13+
-- Android API 21+ (Android 5.0 Lollipop)
-- Swift 5.3+
-- Kotlin 1.8+
+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;
+  }
+};
+```
 
 ---
 
-## Contributing
+### Deep Links and Navigation
 
-We welcome contributions! To get started:
+Handle deep links from push notifications:
 
-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)
+#### Setup Deep Linking
 
----
+**1. Configure Deep Links (iOS):**
+
+Add to `ios/YourApp/Info.plist`:
 
-## Support
+```xml
+<key>CFBundleURLTypes</key>
+<array>
+  <dict>
+    <key>CFBundleURLSchemes</key>
+    <array>
+      <string>yourapp</string>
+    </array>
+  </dict>
+</array>
+```
 
-- 📚 [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
+**2. Configure Deep Links (Android):**
 
----
+Add to `android/app/src/main/AndroidManifest.xml`:
 
-## License
+```xml
+<activity android:name=".MainActivity">
+  <!-- Existing intent filter -->
 
-[MIT](LICENSE)
+  <!-- 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" />
 
-## Acknowledgments
+    <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
+
+---
+
+### Next Steps
+
+- Learn about [In-App Messaging](#in-app-messaging)
+- Explore [Deep Link Handling](#deep-links-and-navigation)
+- See [Example Applications](#example-applications) for complete implementations
+
+---
+
+## In-App Messaging
+
+### Event Listeners
+
+Register event listeners to respond to in-app message events:
+
+```typescript
+import { Zixflow, InAppMessageEvent, InAppMessageEventType } from 'zixflow-reactnative';
+import { useEffect } from 'react';
+
+export default function App() {
+  useEffect(() => {
+    const inAppMessaging = Zixflow.inAppMessaging;
+
+    const eventListener = inAppMessaging.registerEventsListener((event: InAppMessageEvent) => {
+      switch (event.eventType) {
+        case InAppMessageEventType.messageShown:
+          console.log('In-app message shown', event);
+          break;
+
+        case InAppMessageEventType.messageDismissed:
+          console.log('In-app message dismissed', event);
+          break;
+
+        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;
+      }
+    });
+
+    // Cleanup listener on unmount
+    return () => {
+      eventListener.remove();
+    };
+  }, []);
+
+  return (
+    // Your app UI
+  );
+}
+```
+
+### Message Events
+
+The SDK provides the following in-app message event types:
+
+| 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`)
+
+### Dismissing Messages
+
+Programmatically dismiss the current in-app message:
+
+```typescript
+import { Zixflow } from 'zixflow-reactnative';
+
+const handleMessageAction = (event: InAppMessageEvent) => {
+  if (event.actionValue === 'dismiss' || event.actionValue === 'close') {
+    // Dismiss the message
+    Zixflow.inAppMessaging.dismissMessage();
+  }
+};
+```
+
+---
+
+## Location Tracking
+
+Enable location tracking to send location-based 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`:
+
+```typescript
+import { request, PERMISSIONS, RESULTS } from 'react-native-permissions';
+import { Platform } from 'react-native';
+
+const requestLocationPermission = async () => {
+  const permission = Platform.select({
+    ios: PERMISSIONS.IOS.LOCATION_WHEN_IN_USE,
+    android: PERMISSIONS.ANDROID.ACCESS_FINE_LOCATION,
+  });
+
+  if (!permission) return;
+
+  const result = await request(permission);
+
+  if (result === RESULTS.GRANTED) {
+    console.log('Location permission granted');
+  }
+};
+```
+
+---
+
+## Advanced Configuration
+
+### Region Settings
+
+Configure the data center region for data residency:
+
+```typescript
+import { Zixflow } from 'zixflow-reactnative';
+
+const config = {
+  apiKey: 'YOUR_API_KEY',
+  // or 
+};
+
+Zixflow.initialize(config);
+```
+
+**Available regions**:
+- `` - United States data center
+- `` - European Union data center
+
+### Log Levels
+
+Control SDK logging for debugging:
+
+```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
+
+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,
+};
+
+Zixflow.initialize(config);
+```
+
+### 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);
+```
+
+---
+
+## Troubleshooting
+
+### Installation Issues
+
+**Issue**: `npm install` fails with dependency conflicts
+
+**Solution**: Use `--legacy-peer-deps` flag:
+```bash
+npm install zixflow-reactnative --legacy-peer-deps
+```
+
+Or with Yarn:
+```bash
+yarn add zixflow-reactnative --legacy-peer-deps
+```
+
+---
+
+**Issue**: Auto-linking fails after installation
+
+**Solution**: Try manual linking:
+
+1. Clean the build:
+```bash
+cd android && ./gradlew clean && cd ..
+cd ios && rm -rf Pods && pod install && cd ..
+```
+
+2. Rebuild the app:
+```bash
+npx react-native run-ios
+npx react-native run-android
+```
+
+### iOS Build Errors
+
+**Issue**: `Module 'Zixflow' not found`
+
+**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
+
+---
+
+**Issue**: Swift compiler errors in native modules
+
+**Solution**:
+1. Check Xcode version (14.0+ required)
+2. Update CocoaPods: `sudo gem install cocoapods`
+3. Update pod dependencies: `cd ios && pod update && cd ..`
+
+---
+
+**Issue**: Notification Service Extension not working
+
+**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
+
+### Android Build Errors
+
+**Issue**: `Cannot find symbol class Zixflow`
+
+**Solution**:
+1. Clean Gradle cache:
+```bash
+cd android && ./gradlew clean && cd ..
+```
+
+2. Rebuild the app:
+```bash
+npx react-native run-android
+```
+
+---
+
+**Issue**: Duplicate class errors with Firebase
+
+**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
+```
+
+---
+
+**Issue**: Minimum SDK version error
+
+**Solution**: Update `android/build.gradle`:
+```gradle
+ext {
+    minSdkVersion = 24
+}
+```
+
+### Push Notification Issues
+
+**Issue**: Push notifications not received on iOS
+
+**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)
+
+---
+
+**Issue**: Push notifications not received on Android
+
+**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+)
+
+---
+
+**Issue**: Rich push notifications (images) not working
+
+**Solution**: Ensure Notification Service Extension is properly configured on iOS (see [Notification Service Extension](#notification-service-extension))
+
+### In-App Message Issues
+
+**Issue**: In-app messages not displaying
+
+**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
+
+---
+
+**Issue**: In-app message events not firing
+
+**Solution**: Ensure event listener is registered before messages are triggered:
+```typescript
+useEffect(() => {
+  const listener = Zixflow.inAppMessaging.registerEventsListener((event) => {
+    console.log('In-app event:', event);
+  });
+
+  return () => listener.remove();
+}, []);
+```
+
+---
+
+## Example Applications
+
+The Zixflow React Native SDK includes example applications demonstrating best practices:
+
+### Sample App (APNs)
+
+Location: `example/`
+
+**Features**:
+- User identification and logout
+- Event tracking
+- Screen tracking with React Navigation
+- Push notifications with APNs
+- In-app messaging with event listeners
+- Profile and device attributes
+
+**Running the example**:
+
+```bash
+# Install dependencies
+cd example
+npm install
+
+# iOS
+cd ios && pod install && cd ..
+npx react-native run-ios
+
+# Android
+npx react-native run-android
+```
+
+---
+
+## API Reference
+
+### Core SDK
+
+#### `Zixflow.initialize(config: ZixflowConfig): void`
+
+Initialize the SDK with configuration.
+
+```typescript
+Zixflow.initialize({
+  apiKey: 'YOUR_API_KEY',
+});
+```
+
+#### `Zixflow.identify(params: { userId: string; traits?: object }): void`
+
+Identify a user with optional traits.
+
+```typescript
+Zixflow.identify({
+  userId: 'user-123',
+  traits: { email: 'user@example.com' }
+});
+```
+
+#### `Zixflow.clearIdentify(): void`
+
+Clear the current user's identity.
+
+```typescript
+Zixflow.clearIdentify();
+```
+
+#### `Zixflow.track(name: string, properties?: object | Map<string, any>): void`
+
+Track a custom event.
+
+```typescript
+Zixflow.track('button_clicked', { button_name: 'signup' });
+```
+
+#### `Zixflow.screen(name: string, properties?: object): void`
+
+Track a screen view.
+
+```typescript
+Zixflow.screen('HomeScreen');
+```
+
+#### `Zixflow.setProfileAttributes(attributes: object): void`
+
+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;
+  region?: Region;
+  logLevel?: ZixflowLogLevel;
+  inApp?: {
+  };
+  autoTrackDeviceAttributes?: boolean;
+  trackApplicationLifecycleEvents?: boolean;
+  autoTrackScreenViews?: boolean;
+  trackingApiUrl?: string;
+}
+```
+
+#### `Region`
+
+Data center region enum.
+
+```typescript
+enum Region {
+  US = 'US',
+  EU = 'EU'
+}
+```
+
+#### `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`
+
+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;
+}
+```
+
+---
+
+## 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.
+
+---
 
-This SDK is based on the Zixflow React Native SDK and maintains compatibility with the Zixflow platform while providing Zixflow-specific optimizations and branding.
+**Need help?** Contact our support team at support@zixflow.com or open an issue on GitHub.