Zixflow React Native SDK - Integration Guide

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.

Table of Contents

1. Introduction
2. Requirements
3. Installation
   • npm Installation
   • Yarn Installation
4. iOS Setup
   • CocoaPods Integration
   • Swift Package Manager Integration
   • Push Notification Setup (APNs)
   • Notification Service Extension
5. Android Setup
   • Gradle Configuration
   • Firebase Cloud Messaging Setup
6. Quick Start
   • Basic Configuration
   • SDK Initialization
7. Core Features
   • User Identification
   • Event Tracking
   • Screen Tracking
   • User Profile Attributes
   • Device Attributes
   • Clearing User Identity
8. Push Notifications
   • Requesting Permission
   • Handling Push Notifications
   • Device Token Registration
9. In-App Messaging
   • Event Listeners
   • Message Events
   • Dismissing Messages
10. Location Tracking
11. Advanced Configuration
    • Region Settings
    • Log Levels
    • Auto-Tracking Options
    • Custom API Hosts
12. Troubleshooting
    • Installation Issues
    • iOS Build Errors
    • Android Build Errors
    • Push Notification Issues
    • In-App Message Issues
13. Example Applications
14. API Reference
15. Support & Resources

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

npm Installation

Install the SDK using npm:

npm install zixflow-reactnative

Yarn Installation

Or install using Yarn:

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:

cd ios

2. Install CocoaPods dependencies:

pod install

3. Open the workspace in Xcode:

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:

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:

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:

buildscript {
    ext {
        minSdkVersion = 24
        compileSdkVersion = 34
        targetSdkVersion = 34
    }
}

2. Add Maven repositories in android/build.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
   • Add your Android app
   • Download google-services.json and place it in android/app/

2. Add Google Services plugin in android/build.gradle:

buildscript {
    dependencies {
        classpath 'com.google.gms:google-services:4.4.2'
    }
}

3. Apply the plugin in android/app/build.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:

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:

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:

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: '[email protected]',
    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:

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:

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:

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:

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:

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:

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+)

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:

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:

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:

cd ios
pod install
cd ..

Step 3: Configure AppDelegate (Swift - Recommended)

For modern Swift-based React Native apps with APNs:

AppDelegate.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:

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:

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:

#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:

# 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:

target 'NotificationServiceExtension' do
  pod 'zixflow-reactnative-richpush/fcm', :path => '../node_modules/zixflow-reactnative'
end

3. Install dependencies:

cd ios
pod install
cd ..

4. Update NotificationService.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
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:

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:

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:

<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:

<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:

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:

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:

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.

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()
• Device tokens are automatically removed from previous profiles when identifying new users
• This prevents duplicate notifications when users switch accounts

Step 5: Get Device Token

Retrieve the registered device token:

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:

<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:

<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:

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

{
  "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

{
  "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

{
  "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:

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:

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
• Explore Deep Link Handling
• See Example Applications for complete implementations

In-App Messaging

Event Listeners

Register event listeners to respond to in-app message events:

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:

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:

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:

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:

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:

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:

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:

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:

npm install zixflow-reactnative --legacy-peer-deps

Or with Yarn:

yarn add zixflow-reactnative --legacy-peer-deps

Issue: Auto-linking fails after installation

Solution: Try manual linking:

1. Clean the build:

cd android && ./gradlew clean && cd ..
cd ios && rm -rf Pods && pod install && cd ..

2. Rebuild the app:

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:

cd android && ./gradlew clean && cd ..

2. Rebuild the app:

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:

android.enableJetifier=true

Issue: Minimum SDK version error

Solution: Update android/build.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)

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:

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:

# 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.

Zixflow.initialize({
  apiKey: 'YOUR_API_KEY',
});

Zixflow.identify(params: { userId: string; traits?: object }): void

Identify a user with optional traits.

Zixflow.identify({
  userId: 'user-123',
  traits: { email: '[email protected]' }
});

Zixflow.clearIdentify(): void

Clear the current user's identity.

Zixflow.clearIdentify();

Zixflow.track(name: string, properties?: object | Map<string, any>): void

Track a custom event.

Zixflow.track('button_clicked', { button_name: 'signup' });

Zixflow.screen(name: string, properties?: object): void

Track a screen view.

Zixflow.screen('HomeScreen');

Zixflow.setProfileAttributes(attributes: object): void

Set attributes on the user profile.

Zixflow.setProfileAttributes({ plan: 'premium' });

Zixflow.setDeviceAttributes(attributes: object): void

Set attributes on the current device.

Zixflow.setDeviceAttributes({ app_version: '2.0.0' });

Push Messaging

Zixflow.pushMessaging.showPromptForPushNotifications(options): Promise<ZixflowPushPermissionStatus>

Request push notification permission.

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.

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.

Zixflow.inAppMessaging.dismissMessage();

Types

ZixflowConfig

Configuration object for SDK initialization.

interface ZixflowConfig {
  apiKey: string;
  region?: Region;
  logLevel?: ZixflowLogLevel;
  inApp?: {
  };
  autoTrackDeviceAttributes?: boolean;
  trackApplicationLifecycleEvents?: boolean;
  autoTrackScreenViews?: boolean;
  trackingApiUrl?: string;
}

Region

Data center region enum.

enum Region {
  US = 'US',
  EU = 'EU'
}

ZixflowLogLevel

Log level enum.

enum ZixflowLogLevel {
  none = 'none',
  error = 'error',
  info = 'info',
  debug = 'debug'
}

ZixflowPushPermissionStatus

Push notification permission status.

enum ZixflowPushPermissionStatus {
  Granted = 'granted',
  Denied = 'denied',
  NotDetermined = 'notDetermined'
}

InAppMessageEventType

In-app message event types.

enum InAppMessageEventType {
  messageShown = 'messageShown',
  messageDismissed = 'messageDismissed',
  messageActionTaken = 'messageActionTaken',
  errorWithMessage = 'errorWithMessage'
}

InAppMessageEvent

In-app message event object.

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 section above

Getting Help

• GitHub Issues: https://github.com/zixflow/zixflow-reactnative/issues
• Support Email: [email protected]

Changelog

See CHANGELOG.md for version history and release notes.

Need help? Contact our support team at [email protected] or open an issue on GitHub.