OnboardSync Expo SDK

The official Expo SDK for OnboardSync - a remote configuration platform for mobile app onboarding flows with A/B testing capabilities.

Features

• 🚀 Simple Integration - Single method to show onboarding
• 🎨 WebView-Based - Dynamic content without app updates
• 📊 A/B Testing - Built-in flow experimentation
• 🔒 Secure - Authenticated API access
• 📱 Cross-Platform - iOS and Android support
• 🎯 Smart Targeting - Device-based flow resolution
• 🔧 Zero Configuration - Works out of the box
• 📈 Analytics - Automatic event tracking
• 🎪 Expo Go Compatible - Works with Expo Go out of the box

Requirements

• Expo SDK 47.0.0 or higher
• iOS 11.0+
• Android API 21+

Installation

npm install onboardsync-react-native
# or
yarn add onboardsync-react-native

Install Peer Dependencies

Install the required Expo packages:

npx expo install expo-application expo-camera expo-contacts expo-crypto expo-device expo-location expo-media-library expo-notifications expo-secure-store expo-store-review react-native-webview

iOS Setup

1. Install pods:

cd ios && pod install

2. Add the following to your ios/YourApp/Info.plist:

<key>NSCameraUsageDescription</key>
<string>This app needs access to camera to take photos</string>
<key>NSPhotoLibraryUsageDescription</key>
<string>This app needs access to photo library to select images</string>
<key>NSLocationWhenInUseUsageDescription</key>
<string>This app needs access to location for personalized experiences</string>
<key>NSContactsUsageDescription</key>
<string>This app needs access to contacts to help you connect with friends</string>

Android Setup

Add the following permissions to your android/app/src/main/AndroidManifest.xml:

<uses-permission android:name="android.permission.CAMERA" />
<uses-permission android:name="android.permission.READ_EXTERNAL_STORAGE" />
<uses-permission android:name="android.permission.ACCESS_FINE_LOCATION" />
<uses-permission android:name="android.permission.READ_CONTACTS" />
<uses-permission android:name="android.permission.POST_NOTIFICATIONS" />

Quick Start

import React, { useState } from 'react';
import { View, Text } from 'react-native';
import { OnboardSyncComponent, OnboardingResult } from 'onboardsync-react-native';

function App() {
  const [showOnboarding, setShowOnboarding] = useState(true);
  
  const handleComplete = (result?: OnboardingResult) => {
    console.log('Onboarding completed!');
    
    // Access form responses if available
    if (result) {
      result.responses.forEach(response => {
        console.log(`${response.questionText}: ${response.answer}`);
      });
    }
    
    setShowOnboarding(false);
  };
  
  return (
    <View style={{ flex: 1 }}>
      <Text>Welcome to my app!</Text>
      
      {showOnboarding && (
        <OnboardSyncComponent
          projectId="[project_key]"
          secretKey="[secret_key]"
          onComplete={handleComplete}
        />
      )}
    </View>
  );
}

Configuration

OnboardSyncConfig

| Property | Type | Required | Description | |----------|------|----------|-------------| | projectId | string | Yes | Your OnboardSync project ID | | secretKey | string | Yes | Your OnboardSync secret key | | testingEnabled | boolean | No | Show onboarding every time (default: false) | | onComplete | (result?: OnboardingResult) => void | No | Callback when onboarding completes with form responses |

Example

const config = {
  projectId: '[project_key]',
  secretKey: '[secret_key]',
  testingEnabled: true, // For development
  onComplete: (result) => {
    console.log('User completed onboarding');
    
    // Access form responses
    if (result && result.responses.length > 0) {
      console.log('Form responses:', JSON.stringify(result, null, 2));
    }
    
    // Navigate to main app
  }
};

<OnboardSyncComponent {...config} />

How It Works

1. Device Identification: The SDK generates and persists a unique device ID
2. Flow Resolution: Contacts OnboardSync API to determine which flow to show
3. WebView Display: Shows the onboarding content in a full-screen WebView
4. Completion Tracking: Automatically tracks completion status locally
5. Analytics: Sends events for flow starts, step views, and completions

Features

Automatic Completion Tracking

The SDK automatically tracks when a user completes onboarding and won't show it again unless testingEnabled is true.

JavaScript Bridge

The WebView communicates with the native app through a JavaScript bridge supporting:

• Close: User can exit onboarding
• Theme Updates: Dynamic status bar styling
• Permissions: Camera, photos, location, contacts, notifications
• App Rating: Trigger native app store rating dialog
• Completion: Mark onboarding as complete
• Form Responses: Send form responses as JSON to the SDK

Fallback UI

If the onboarding flow can't be loaded (offline, errors), a simple native welcome screen is shown.

Permission Handling

The SDK handles runtime permissions automatically when requested by the onboarding flow:

// In your onboarding web content
window.flutter_bridge.postMessage({
  type: 'requestPermission',
  data: { permission: 'camera' }
});

Testing Mode

Enable testing mode to show onboarding every time:

<OnboardSyncComponent
  projectId="..."
  secretKey="..."
  testingEnabled={true}
/>

Clear Completion Status

For development/testing, you can clear the completion status:

import { DeviceIDManager } from 'onboardsync-react-native';

// Clear completion for a specific project
await DeviceIDManager.clearCompletionStatus(projectId);

Advanced Usage

Custom Loading Screen

import { WebViewScreen, LoadingScreen } from 'onboardsync-react-native';

// Use the components directly for custom integration

Access Device ID

import { DeviceIDManager } from 'onboardsync-react-native';

const deviceId = await DeviceIDManager.getDeviceId();

Custom Styling

The SDK respects your app's theme and adapts the status bar based on the onboarding background color.

Platform Differences

iOS

• Uses WKWebView
• Supports iOS 11.0+
• Status bar styling via UIStatusBarStyle

Android

• Uses Android WebView
• Supports API 21+
• Status bar coloring on API 21+

Troubleshooting

WebView Not Loading

1. Check network connectivity
2. Verify project ID and secret key
3. Ensure OnboardSync backend is accessible

Permissions Not Working

1. Ensure permissions are declared in your app manifests
2. For iOS, add usage descriptions in Info.plist
3. For Android, add permissions in AndroidManifest.xml

Onboarding Shows Every Time

Check if testingEnabled is set to true. Set it to false for production.

Status Bar Issues

The SDK automatically manages status bar appearance. If you need custom behavior, you can use the StatusBarHelper utility class.

API Reference

OnboardSyncComponent

Main component to display onboarding.

<OnboardSyncComponent
  projectId="string"
  secretKey="string"
  testingEnabled={boolean}
  onComplete={(result?: OnboardingResult) => void}
/>

OnboardingResult

Contains all form responses from a completed onboarding flow.

interface OnboardingResult {
  flowId: string;                    // The ID of the completed flow
  responses: OnboardingResponse[];   // All form responses
}

OnboardingResponse

A single question response from the onboarding flow.

interface OnboardingResponse {
  questionText: string;              // The question that was asked
  questionType: string;              // 'question_text', 'question_single_choice', or 'question_multiple_choice'
  answer: string | string[];         // The user's answer
  screenId?: string;                 // The screen ID where this question appeared
}

OnboardingResultHelper

Helper class for working with form responses.

import { OnboardingResultHelper } from 'onboardsync-react-native';

const helper = new OnboardingResultHelper(result);

// Get a specific response by question text
const response = helper.getResponseByQuestion("What's your name?");

// Get responses by type
const textResponses = helper.textResponses;
const singleChoiceResponses = helper.singleChoiceResponses;
const multipleChoiceResponses = helper.multipleChoiceResponses;
const allChoiceResponses = helper.choiceResponses;

// Check if there are responses
if (helper.hasResponses) {
  console.log(`Got ${helper.responseCount} responses`);
}

DeviceIDManager

Utility for managing device ID and completion status.

// Get device ID
const id = await DeviceIDManager.getDeviceId();

// Check completion
const completed = await DeviceIDManager.isOnboardingCompleted(projectId);

// Mark complete
await DeviceIDManager.markOnboardingCompleted(projectId);

// Clear status
await DeviceIDManager.clearCompletionStatus(projectId);

PermissionsHandler

Handle system permissions.

const granted = await PermissionsHandler.requestPermission('camera');

ColorUtils

Color manipulation utilities.

const isDark = ColorUtils.isColorDark('#000000'); // true
const contrast = ColorUtils.getContrastColor('#FFFFFF'); // '#000000'

Example App

See the example directory for a complete React Native app demonstrating all features.

cd example
npm install
cd ios && pod install
npm run ios # or npm run android

Support

• 📧 Email: [email protected]
• 📚 Documentation: https://docs.onboardsync.com

License

MIT - see LICENSE for details.