React Native SDK

Integrate OnboardSync with your React Native application

The React Native SDK supports Expo SDK 47.0+ and requires expo-dev-client for development builds.

Installation

Add OnboardSync to your React Native project:

npm

npm install onboardsync-react-native

iOS Setup

cd ios && pod install

Add required permissions to your Info.plist based on your onboarding flow:

<!-- Camera permission -->
<key>NSCameraUsageDescription</key>
<string>This app needs camera access for profile photos</string>

<!-- Photo library permission -->
<key>NSPhotoLibraryUsageDescription</key>
<string>This app needs photo library access to select images</string>

<!-- Location permission -->
<key>NSLocationWhenInUseUsageDescription</key>
<string>This app needs location access to provide local features</string>

Android Setup

For Expo managed workflow, ensure you’re using a development build:

eas build --profile development --platform all

Add required permissions to app.json:

{
  "expo": {
    "plugins": [
      [
        "expo-camera",
        {
          "cameraPermission": "Allow app to access your camera."
        }
      ],
      [
        "expo-location",
        {
          "locationAlwaysAndWhenInUsePermission": "Allow app to use your location."
        }
      ]
    ]
  }
}

Basic Usage

Component-Based Approach (Recommended)

import React from 'react';
import { OnboardSyncComponent } from 'onboardsync-react-native';
import { useNavigation } from '@react-navigation/native';

const OnboardingScreen = () => {
  const navigation = useNavigation();

  return (
    <OnboardSyncComponent
      projectId="your-project-id"
      secretKey="your-secret-key" // Get from dashboard
      onComplete={(result) => {
        // Access form responses if available
        if (result && result.responses.length > 0) {
          result.responses.forEach(response => {
            console.log(`${response.questionText}: ${response.answer}`);
          });
        }
        
        // Navigate to main app after completion
        navigation.replace('MainApp');
      }}
      testingEnabled={true} // Optional: Show onboarding every time
    />
  );
};

export default OnboardingScreen;

Configuration Options

<OnboardSyncComponent
  projectId="your-project-id"
  secretKey="your-secret-key"
  testingEnabled={true}                    // Optional
  onComplete={(result) => {                // Receives form responses
    if (result) {
      console.log('Responses:', result.responses);
    }
  }}
/>

projectId · string · required

Your project ID from the OnboardSync dashboard

secretKey · string · required

Your secret key from the OnboardSync dashboard (found in API Keys section)

testingEnabled · boolean · default: "false"

Enable testing mode to show onboarding every time (ignores completion status)

onComplete · (result?: OnboardingResult) => void · required

Callback function called when onboarding completes, receives optional OnboardingResult with form responses

API Reference

OnboardSyncComponent

The main component for displaying onboarding:

import { OnboardSyncComponent, OnboardingResult } from 'onboardsync-react-native';

<OnboardSyncComponent
  projectId="your-project-id"
  secretKey="your-secret-key"
  onComplete={(result) => {
    if (result) {
      console.log('Got responses:', result.responses);
    }
  }}
/>

OnboardingResult

Contains all form responses from a completed onboarding flow:

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

OnboardingResponse

A single question response:

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

OnboardingResultHelper

Helper class for working with form responses:

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

const helper = new OnboardingResultHelper(result);
const nameResponse = helper.getResponseByQuestion("What's your name?");
const textResponses = helper.textResponses;
const hasResponses = helper.hasResponses;

Testing & Development

For testing, you can reset the onboarding status:

import AsyncStorage from '@react-native-async-storage/async-storage';

// Clear stored completion status (for testing)
const resetOnboardingForTesting = async () => {
  await AsyncStorage.removeItem('onboardsync_completed');
  await AsyncStorage.removeItem('onboardsync_device_id');
};

Permission Handling

The SDK automatically handles permission requests configured in your onboarding flow:

// Permissions are requested based on your flow configuration
// The SDK handles these permissions automatically:
// - Camera (expo-camera)
// - Photo library (expo-media-library)
// - Location (expo-location)
// - Notifications (expo-notifications)
// - Contacts (expo-contacts)

// No additional code needed - permissions are requested
// when the corresponding screen is displayed

Navigation Integration

React Navigation

import { NavigationContainer } from '@react-navigation/native';
import { createStackNavigator } from '@react-navigation/stack';
import { OnboardSyncComponent } from 'onboardsync-react-native';

const Stack = createStackNavigator();

function App() {
  return (
    <NavigationContainer>
      <Stack.Navigator initialRouteName="Onboarding">
        <Stack.Screen 
          name="Onboarding" 
          options={{ headerShown: false }}
        >
          {(props) => (
            <OnboardSyncComponent
              projectId="your-project-id"
              secretKey="your-secret-key"
              onComplete={() => {
                props.navigation.replace('Home');
              }}
            />
          )}
        </Stack.Screen>
        <Stack.Screen name="Home" component={HomeScreen} />
      </Stack.Navigator>
    </NavigationContainer>
  );
}

Error Handling

try {
  await onboardSync.showOnboarding();
} catch (error) {
  if (error.code === 'NETWORK_ERROR') {
    // Handle network errors
    Alert.alert('Network Error', 'Please check your connection');
  } else if (error.code === 'INVALID_PROJECT') {
    // Handle invalid project ID
    Alert.alert('Configuration Error', 'Invalid project ID');
  } else {
    // Handle other errors
    console.error('OnboardSync Error:', error);
  }
}

TypeScript Support

The SDK includes full TypeScript support:

import { OnboardSyncComponent, OnboardSyncComponentProps } from 'onboardsync-react-native';

const OnboardingScreen: React.FC = () => {
  const handleComplete = (): void => {
    console.log('Onboarding completed');
  };

  const handleError = (error: Error): void => {
    console.error('Onboarding error:', error);
  };

  const props: OnboardSyncComponentProps = {
    projectId: 'your-project-id',
    secretKey: 'your-secret-key',
    onComplete: handleComplete,
    testingEnabled: true,
  };

  return <OnboardSyncComponent {...props} />;
};

Troubleshooting

WebView not displaying

Ensure react-native-webview is properly installed and linked

Network errors on Android

Check that internet permission is added to AndroidManifest.xml

iOS build failures

Run cd ios && pod install after installation

Onboarding shows on every app launch

Verify that AsyncStorage is working correctly for persistence

Platform Differences

iOS

• Requires iOS 11.0+
• Uses WKWebView for rendering
• Supports safe area insets automatically

Android

• Requires Android 5.0+ (API 21)
• Uses Chrome WebView
• Hardware back button closes onboarding

Example Implementation

View our React Native example app for a complete implementation.

Platform Support

• Expo SDK 47.0+
• React Native 0.72+
• iOS 13.0+
• Android 5.0+ (API 21+)

Next Steps

Flutter SDK

Compare with Flutter implementation

API Reference

Explore the REST API