Installation et configuration

Ce guide vous accompagne dans l'installation et la configuration de Mini-Zoe dans votre projet React Native.

Prérequis

Avant de commencer, assurez-vous d'avoir :

• Node.js >= 14
• Un projet React Native fonctionnel
• Accès au registry GitHub Packages (si le package est privé)

Installation

1. Installer Mini-Zoe

npm install @blueshork/mini-zoe

Ou avec yarn :

yarn add @blueshork/mini-zoe

2. Installer les dépendances natives

Mini-Zoe nécessite plusieurs dépendances natives pour fonctionner :

npm install @react-native-voice/voice react-native-fast-tflite mobx mobx-react

Dépendances requises

• @react-native-voice/voice - Reconnaissance vocale
• react-native-fast-tflite - Modèle TensorFlow Lite pour la prédiction
• mobx et mobx-react - Gestion d'état

3. Installation des pods iOS

cd ios && pod install && cd ..

Avec GitHub Packages

Le package est hébergé sur GitHub Packages, vous devez configurer l'authentification.

Seul les membres autorisés ont accès au repository actuellement.

1. Créer un token GitHub

1. Allez sur GitHub Settings > Developer settings > Personal access tokens
2. Créez un nouveau token avec le scope read:packages
3. Copiez le token généré

2. Configurer .npmrc

Créez un fichier .npmrc à la racine de votre projet :

@blueshork:registry=https://npm.pkg.github.com
//npm.pkg.github.com/:_authToken=${GITHUB_TOKEN}

3. Définir la variable d'environnement

export GITHUB_TOKEN=votre_token_ici

Ou ajoutez-le dans votre fichier .env :

GITHUB_TOKEN=votre_token_ici

4. Installer le package

npm install @blueshork/mini-zoe

Configuration des permissions

iOS

Dans votre fichier ios/YourApp/Info.plist, ajoutez les permissions pour le microphone :

<key>NSSpeechRecognitionUsageDescription</key>
<string>Nous avons besoin d'accéder au microphone pour la reconnaissance vocale</string>
<key>NSMicrophoneUsageDescription</key>
<string>Nous avons besoin d'accéder au microphone pour la reconnaissance vocale</string>

Dans ios/Podfile, ajoutez cette configuration post-install :

post_install do |installer|
  installer.pods_project.targets.each do |target|
    target.build_configurations.each do |config|
      config.build_settings['ENABLE_BITCODE'] = 'NO'
    end
  end
end

Android

Dans android/app/src/main/AndroidManifest.xml, ajoutez les permissions :

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

Fichiers assets requis

Pour utiliser la reconnaissance vocale, vous devez fournir 3 fichiers dans votre projet :

1. vectorizer.json

Dictionnaire pour la vectorisation du texte reconnu :

{
  "aller": 0,
  "vers": 1,
  "profil": 2,
  "accueil": 3,
  "paramètres": 4
}

2. routes.json

Mapping des indices de prédiction vers les noms de routes React Navigation :

{
  "0": "Home",
  "1": "Profile",
  "2": "Settings"
}

3. model.tflite

Votre modèle TensorFlow Lite entraîné pour prédire les routes depuis les commandes vocales.

Organisation des fichiers

Placez ces fichiers dans un dossier assets/ à la racine de votre projet :

your-app/
├── assets/
│   ├── vectorizer.json
│   ├── routes.json
│   └── model.tflite

Configuration initiale

Configuration complète dans App.tsx

import React, { useEffect } from 'react';
import { View, SafeAreaView } from 'react-native';
import { useNavigation } from '@react-navigation/native';
import { MiniZoe, VoiceRecognitionStore } from '@blueshork/mini-zoe';

// Importez vos fichiers de configuration
import vectorizerData from './assets/vectorizer.json';
import routeIndexToName from './assets/routes.json';
const modelPath = require('./assets/model.tflite');

function App() {
  const navigation = useNavigation();

  useEffect(() => {
    // 1. Initialiser Mini-Zoe avec vos assets
    VoiceRecognitionStore.initialize(
      vectorizerData,
      routeIndexToName,
      modelPath
    );

    // 2. Configurer la navigation
    VoiceRecognitionStore.setNavigation(navigation);

    // 3. Démarrer la reconnaissance vocale
    VoiceRecognitionStore.startRecognition();

    // Cleanup lors du démontage
    return () => {
      VoiceRecognitionStore.stopRecognition();
      VoiceRecognitionStore.destroy();
    };
  }, [navigation]);

  return (
    <SafeAreaView style={{ flex: 1 }}>
      <View style={{ flex: 1 }}>
        {/* Votre contenu d'application */}

        {/* Mini-Zoe - à placer en fin de composant */}
        <MiniZoe enabled={true} />
      </View>
    </SafeAreaView>
  );
}

export default App;

Position du composant

Placez <MiniZoe /> à la fin de votre arbre de composants pour qu'il s'affiche au-dessus de tout le contenu.

Demander les permissions au runtime

Pour Android, il est recommandé de demander la permission microphone au runtime :

import { PermissionsAndroid, Platform } from 'react-native';

const requestMicrophonePermission = async () => {
  if (Platform.OS === 'android') {
    const granted = await PermissionsAndroid.request(
      PermissionsAndroid.PERMISSIONS.RECORD_AUDIO,
      {
        title: 'Permission Microphone',
        message: 'Cette application a besoin d\'accéder au microphone pour la reconnaissance vocale',
        buttonPositive: 'OK',
      }
    );
    return granted === PermissionsAndroid.RESULTS.GRANTED;
  }
  return true;
};

// Dans votre composant
useEffect(() => {
  requestMicrophonePermission().then(granted => {
    if (granted) {
      VoiceRecognitionStore.startRecognition();
    }
  });
}, []);

Configuration Text-to-Speech (optionnel)

Si vous souhaitez activer la synthèse vocale, installez la dépendance supplémentaire :

npm install react-native-tts

Puis dans votre code iOS (si vous ciblez iOS), liez la bibliothèque native :

cd ios && pod install && cd ..

Activez ensuite le TTS dans votre composant :

<MiniZoe
  enabled={true}
  enableTextToSpeech={true}
  ttsLanguage="fr-FR"
/>

Vérification de l'installation

Test basique de l'affichage

import { VoiceRecognitionStore } from '@blueshork/mini-zoe';

// Dans un bouton ou à l'initialisation
VoiceRecognitionStore.show('Mini-Zoe est installé !');

Test de la reconnaissance vocale

import { Button } from 'react-native';

function TestButton() {
  const testVoiceRecognition = () => {
    const isActive = VoiceRecognitionStore.isRecognizing;
    console.log('Reconnaissance vocale active:', isActive);
  };

  return <Button title="Tester la reconnaissance" onPress={testVoiceRecognition} />;
}

Si vous voyez l'assistant apparaître en bas à droite et que la reconnaissance vocale fonctionne, félicitations ! 🎉

Prochaines étapes

• Configuration de la reconnaissance vocale - Configurez et personnalisez la reconnaissance vocale
• Guide d'utilisation basique - Apprenez à utiliser Mini-Zoe
• Référence API Store - Découvrez toutes les méthodes disponibles
• Personnalisation - Adaptez Mini-Zoe à votre charte graphique

Résolution de problèmes

Le composant ne s'affiche pas

• Vérifiez que enabled={true} est bien défini
• Assurez-vous que le composant est placé après votre contenu principal
• Vérifiez qu'il n'y a pas d'erreurs dans la console

Le microphone ne fonctionne pas

• iOS : Vérifiez que les clés NSSpeechRecognitionUsageDescription et NSMicrophoneUsageDescription sont bien dans Info.plist
• Android : Vérifiez que les permissions sont dans AndroidManifest.xml
• Demandez les permissions au runtime (voir section ci-dessus)
• Vérifiez que l'utilisateur a accordé les permissions dans les paramètres de l'appareil

Le modèle ne se charge pas

• Vérifiez que le fichier model.tflite existe bien dans vos assets
• Assurez-vous que le chemin vers le modèle est correct
• Sur iOS, vérifiez que le fichier est inclus dans le bundle (Build Phases > Copy Bundle Resources)
• Sur Android, placez le fichier dans android/app/src/main/assets/

Erreur "vectorizer is undefined"

• Vérifiez que les fichiers vectorizer.json et routes.json sont bien importés
• Assurez-vous d'appeler VoiceRecognitionStore.initialize() avant d'utiliser la reconnaissance vocale

Le TTS ne fonctionne pas

• Vérifiez que react-native-tts est bien installé
• Sur iOS, assurez-vous d'avoir lancé pod install
• Vérifiez les permissions de votre appareil

Erreur d'authentification GitHub

• Vérifiez que votre token GitHub est valide
• Assurez-vous que le token a le scope read:packages
• Vérifiez que la variable GITHUB_TOKEN est bien définie