onboardsync-react-native/README.md

Expo SDK for OnboardSync - Remote onboarding configuration platform with A/B testing

# OnboardSync Expo SDK

The official Expo SDK for [OnboardSync](https://onboardsync.com) - 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

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

### Install Peer Dependencies

Install the required Expo packages:

```bash
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:
```bash
cd ios && pod install
```

2. Add the following to your `ios/YourApp/Info.plist`:
```xml
<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`:

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

```tsx
import React, { useEffect } from 'react';
import { View, Text } from 'react-native';
import { OnboardSyncComponent } from 'onboardsync-react-native';

function App() {
  const [showOnboarding, setShowOnboarding] = useState(true);
  
  const handleComplete = () => {
    console.log('Onboarding completed!');
    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` | () => void | No | Callback when onboarding completes |

### Example

```tsx
const config = {
  projectId: '[project_key]',
  secretKey: '[secret_key]',
  testingEnabled: true, // For development
  onComplete: () => {
    console.log('User completed onboarding');
    // 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

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

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

### Testing Mode

Enable testing mode to show onboarding every time:

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

### Clear Completion Status

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

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

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

## Advanced Usage

### Custom Loading Screen

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

// Use the components directly for custom integration
```

### Access Device ID

```tsx
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.

```tsx
<OnboardSyncComponent
  projectId="string"
  secretKey="string"
  testingEnabled={boolean}
  onComplete={() => void}
/>
```

### DeviceIDManager

Utility for managing device ID and completion status.

```tsx
// 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.

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

### ColorUtils

Color manipulation utilities.

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

## Example App

See the [example](./example) directory for a complete React Native app demonstrating all features.

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

## Support

- 📧 Email: support@muchadostudio.com
- 📚 Documentation: https://docs.onboardsync.com

## License

MIT - see [LICENSE](./LICENSE) for details.