Guide de connexion iOS/visionOS pour Unity

Portée

S'applique au bHaptics Unity SDK 2.8.0 et versions ultérieures, uniquement sur les appareils physiques iOS et visionOS. Le prefab [bHapticsUIApple] et l'API BhapticsAppleDevices n'ont aucun effet dans l'Éditeur ni sur les autres plateformes. Ne les utilisez que pour iOS/visionOS, et testez toujours sur un appareil physique.

Sur Windows/macOS/Android, l'application bHaptics Player gère les connexions aux appareils. Elle ne peut pas le faire sur iOS/visionOS, car le sandbox applicatif n'autorise pas une application à maintenir une connexion Bluetooth pour le compte d'autres applications. À la place, chaque application recherche les appareils et s'y connecte directement via CoreBluetooth.

Le SDK fournit l'API BhapticsAppleDevices et un prefab d'interface d'exemple, [bHapticsUIApple]. Les étapes ci-dessous utilisent ce prefab.

1. Ajouter une description d'utilisation du Bluetooth
2. Gérer la recherche et la connexion avec le prefab d'interface d'exemple
3. Jouer des effets haptiques

---

Ajouter une description d'utilisation du Bluetooth

Les appareils haptiques communiquent via Bluetooth, votre application a donc besoin de la clé NSBluetoothAlwaysUsageDescription. Le SDK bHaptics ne l'ajoute pas automatiquement, vous devez donc l'ajouter vous-même.

Si vous ne l'ajoutez pas :

• La première fois que votre application accède à CoreBluetooth (par exemple lorsque le SDK initialise son gestionnaire Bluetooth pour reconnecter les appareils appairés, ou lorsqu'il lance une recherche), iOS fait immédiatement planter l'application :

  This app has crashed because it attempted to access privacy-sensitive data
  without a usage description. The app's Info.plist must contain an
  NSBluetoothAlwaysUsageDescription key ...

• La validation à l'envoi sur App Store Connect peut rejeter le build avec l'erreur ITMS-90683 (Missing purpose string) même si votre application n'appelle jamais l'API de recherche à l'exécution, car l'application compilée référence des API CoreBluetooth.

Comment ajouter la description

Dans le projet Xcode généré, sélectionnez la cible principale de l'application (généralement Unity-iPhone pour un build iOS) et ouvrez l'onglet Info. Ajoutez Privacy - Bluetooth Always Usage Description, ou modifiez directement Info.plist :

<key>NSBluetoothAlwaysUsageDescription</key>
<string>This app uses Bluetooth to connect to nearby bHaptics haptic devices (such as TactSuit) and play haptic feedback.</string>

Rédigez un texte spécifique à votre application expliquant pourquoi elle utilise le Bluetooth. App Review peut rejeter un texte vague ou générique (directive 5.1.1).

astuce

La fenêtre d'autorisation apparaît au premier lancement de l'application et affiche ce texte. Utilisez InfoPlist.strings pour la localisation.

Se connecter avec l'interface d'exemple

Le prefab [bHapticsUIApple] est une interface d'exemple qui montre comment rechercher des appareils bHaptics et s'y connecter, en utilisant l'API BhapticsAppleDevices en interne.

N'utilisez le prefab [bHapticsUIApple] que pour iOS/visionOS.

Prérequis

Ce guide suppose que vous avez déjà importé le bHaptics Unity SDK et lié votre application haptique. Si ce n'est pas le cas, consultez d'abord le Guide Unity.

Ajouter le prefab d'interface

Placez le prefab Assets/Bhaptics/SDK2/Prefabs/[bHapticsUIApple] dans votre scène.

Rechercher

• Appuyer sur Scan lance la recherche des appareils bHaptics à proximité.
• La recherche s'arrête automatiquement au bout de 30 secondes ; le bouton affiche un décompte du temps restant. Appuyez à nouveau dessus pour arrêter la recherche immédiatement.
• La liste affiche les appareils trouvés par cette recherche ainsi que les appareils appairés précédemment.

Se connecter

• Appuyer sur Connect pour un appareil l'appaire (le mémorise) et le connecte en une seule étape. L'état passe au vert et affiche Connected.
• Disconnect désappaire (oublie) l'appareil et le déconnecte.

Chaque appareil affiche son état de connexion. Trois états sont possibles :

État	Signification
[Position] - Connected (vert)	Connecté
[Position] - Paired (gris)	Mémorisé, mais pas connecté actuellement
[Position]	Détecté, non appairé

Les connexions sont propres à chaque application

Les informations d'appairage sont stockées dans le sandbox de l'application elle-même, et non dans l'appairage Bluetooth au niveau système de l'application Réglages d'iOS.

• Vous devez appairer séparément dans chaque application. Pour utiliser le même appareil depuis une autre application, connectez-vous à nouveau depuis cette application.
• Une fois appairé, l'appareil se reconnecte automatiquement à la prochaine initialisation du SDK (le prefab [bHaptics] s'en charge au démarrage de votre application).
• Un appareil que vous n'avez pas appairé ne se connecte jamais de lui-même — la recherche et l'appairage sont toujours explicites (utile pour les scénarios multi-utilisateurs et les événements sur site).

Étape suivante : jouer des effets haptiques

La recherche et la connexion fonctionnent indépendamment, mais jouer des événements nécessite que le SDK soit initialisé. L'initialisation est prise en charge par le prefab [bHaptics]. Ajoutez-le à votre première scène (voir Add Prefab for Initialization dans le Guide Unity).

Une fois le prefab en place, jouez les événements comme d'habitude :

BhapticsLibrary.Play("my_event");   // Plays on the connected device

Annexe : contrôler directement sans interface

[bHapticsUIApple] n'est qu'un exemple — vous pouvez créer votre propre interface de connexion avec la même API bas niveau. Consultez Class BhapticsAppleDevices dans les Références.