@syvoice/react-native

SyVoice React Native SDK — أضف مساعد صوتي ذكي لتطبيقك بسطرين فقط

Installation

npm install @syvoice/react-native
# or
yarn add @syvoice/react-native

Required Peer Dependencies

# For real-time audio streaming (required)
npm install react-native-live-audio-stream

# For smooth gapless assistant speech (required for production APK)
npm install react-native-audio-api

# For audio session / permissions (recommended)
npm install expo-av

# For persistent storage (optional)
npm install @react-native-async-storage/async-storage

iOS Setup

cd ios && pod install

Android Permissions

Add to android/app/src/main/AndroidManifest.xml:

<uses-permission android:name="android.permission.RECORD_AUDIO" />
<uses-permission android:name="android.permission.MODIFY_AUDIO_SETTINGS" />

Linking react-native-live-audio-stream

This package requires manual linking. Follow the instructions at: https://github.com/xiwei/react-native-live-audio-stream

Product navigation (guidance → in-app screens)

Uses the same guidance dashboard as the web store (pages, products, nav links). Minimal Expo Router setup:

import { useRouter } from 'expo-router';

const router = useRouter();
const voice = useSyVoice({
  apiKey: 'sv_...',
  storeBaseUrl: 'https://your-store.com',
  appNavigation: {
    mode: 'expo-router',
    router,
    productPath: '/product/[slug]',
    collectionPath: '/collections/[slug]',
  },
});

Or custom: onNavigate: (payload) => { ... } — payload.url, payload.slug, payload.name.

Publish order: @syvoice/[email protected] then @syvoice/[email protected].

Smooth playback (react-native-audio-api)

Assistant speech uses gapless PCM scheduling (same approach as the web SDK). Without react-native-audio-api, playback falls back to chunked WAV files and may stutter on release APKs.

npm install react-native-audio-api
npx expo prebuild   # if using Expo — then rebuild your APK

Docs: https://docs.swmansion.com/react-native-audio-api/

Usage

Basic Usage with Hook

import { useSyVoice, SyVoiceButton, SyVoiceOverlay } from '@syvoice/react-native';
import { View } from 'react-native';

function MyScreen() {
  const voice = useSyVoice({
    apiKey: 'sv_your_key_here',
    language: 'ar',
    dialect: 'gulf', // 'syrian' | 'egyptian' | 'gulf' | 'saudi'
    customContext: 'Current venue: Al Nasr Club. Available courts: Padel 1, Padel 2',
    onConversationEnd: (data) => {
      console.log('Conversation ended:', data);
      // data.transcript, data.duration, data.extractedIntent, etc.
    },
  });

  return (
    <View style={{ flex: 1 }}>
      <SyVoiceButton 
        state={voice.state} 
        onPress={voice.isListening ? voice.stop : voice.start}
        primaryColor="#E53E3E"
      />
      <SyVoiceOverlay 
        visible={voice.state !== 'idle'} 
        state={voice.state}
        transcript={voice.transcript}
        assistantName="مساعد"
      />
    </View>
  );
}

Manual Control

import { VoiceSession, RNWebSocketAdapter, ExpoAudioManager, RNStorageAdapter } from '@syvoice/react-native';
import AsyncStorage from '@react-native-async-storage/async-storage';

const session = new VoiceSession(
  {
    apiKey: 'sv_your_key_here',
    language: 'ar',
    dialect: 'syrian',
    onTranscript: (text, isUser) => {
      console.log(isUser ? 'User:' : 'Assistant:', text);
    },
    onStateChange: (state) => {
      console.log('State:', state); // 'idle' | 'connecting' | 'listening' | 'speaking' | 'error'
    },
  },
  {
    wsFactory: () => new RNWebSocketAdapter(),
    audio: new ExpoAudioManager(),
    storage: new RNStorageAdapter(AsyncStorage),
  }
);

// Initialize and validate API key
await session.init();

// Start voice session
await session.start();

// Send text message
session.sendText('Hello');

// Stop session
session.stop();

// Cleanup
session.destroy();

Features

✅ Implemented

• Real-time Audio Streaming — PCM 16-bit @ 16kHz via WebSocket
• Audio Interruption Handling — Pauses/resumes on phone calls
• Auto-reconnect — 3 attempts with exponential backoff (2s, 4s, 6s)
• Background Audio — Continues recording in background
• 4 Arabic Dialects — Syrian, Egyptian, Gulf, Saudi
• BYOK Support — Bring Your Own Gemini API Key
• Offline Cache — Guidance data cached locally

⚠️ Requirements

• react-native-live-audio-stream is required for real-time audio
• expo-av is required for audio playback
• Android SDK 21+ / iOS 12+
• React Native 0.70+

Configuration

VoiceSession Options

interface SyVoiceMobileConfig {
  apiKey: string;
  apiBaseUrl?: string;      // Default: 'https://www.syvoice.io'
  relayUrl?: string;        // WebSocket relay URL
  mode?: 'guide' | 'support' | 'full';
  language?: 'ar' | 'en';
  dialect?: 'syrian' | 'egyptian' | 'gulf' | 'saudi';
  assistantName?: string;
  industryType?: IndustryType;
  
  // For booking/availability systems
  onQueryAvailability?: (query) => Promise<AvailabilityResult>;
  
  // Called when conversation ends
  onConversationEnd?: (data: ConversationEndData) => void;
  
  // State change callback
  onStateChange?: (state: SessionState) => void;
  
  // Real-time transcripts
  onTranscript?: (text: string, isUser: boolean) => void;
  
  // Error handling
  onError?: (error: SyVoiceError) => void;
  
  // Mobile-specific
  platform?: 'ios' | 'android' | 'react-native';
  bundleId?: string;        // For app validation
}

Troubleshooting

"Real-time audio streaming requires react-native-live-audio-stream"

Install the required package:

npm install react-native-live-audio-stream

iOS: "Audio not working in background"

Enable "Audio, AirPlay, and Picture in Picture" background mode in Xcode:

• Project → Capabilities → Background Modes → Check "Audio, AirPlay, and Picture in Picture"

Android: "Permission denied"

Request runtime permission:

import { PermissionsAndroid } from 'react-native';

const granted = await PermissionsAndroid.request(
  PermissionsAndroid.PERMISSIONS.RECORD_AUDIO
);

Reconnection not working

Check your network connection. The SDK attempts to reconnect 3 times with exponential backoff. If all attempts fail, it calls onError with code 503.

Architecture

┌─────────────────────────────────────────────────────────────┐
│  @syvoice/react-native (UI + Platform Adapters)             │
│  ├── useSyVoice hook                                        │
│  ├── SyVoiceButton / SyVoiceOverlay                         │
│  ├── ExpoAudioManager (react-native-live-audio-stream)    │
│  ├── RNWebSocketAdapter (built-in WebSocket)              │
│  └── RNStorageAdapter (AsyncStorage)                      │
└────────────────────┬────────────────────────────────────────┘
                     │
┌────────────────────▼────────────────────────────────────────┐
│  @syvoice/mobile-core (Platform-Agnostic Core)              │
│  ├── VoiceSession (orchestrator)                            │
│  ├── RelayClient (auto-reconnect, error recovery)           │
│  ├── SessionBuilder (dialect-aware prompts)                 │
│  ├── GuidanceLoader (caching)                               │
│  └── AudioProtocol (PCM conversion)                         │
└─────────────────────────────────────────────────────────────┘

License

Commercial — See LICENSE file

Support

For issues and support, contact: [email protected]