Guía de conexión en iOS/visionOS para Unity

Ámbito de aplicación

Se aplica al bHaptics Unity SDK 2.8.0 o superior, únicamente en dispositivos físicos iOS y visionOS. El prefab [bHapticsUIApple] y la API BhapticsAppleDevices no hacen nada en el Editor ni en otras plataformas. Úselos solo para iOS/visionOS y pruebe siempre en un dispositivo físico.

En Windows/macOS/Android, la aplicación bHaptics Player gestiona las conexiones de los dispositivos. En iOS/visionOS no puede hacerlo, porque el sandbox de aplicaciones no permite que una aplicación mantenga una conexión Bluetooth para otras. En su lugar, cada aplicación busca y se conecta a los dispositivos directamente a través de CoreBluetooth.

El SDK ofrece la API BhapticsAppleDevices y un prefab de UI de ejemplo, [bHapticsUIApple]. Los pasos siguientes utilizan ese prefab.

1. Añadir una descripción de uso de Bluetooth
2. Gestionar la búsqueda y la conexión con el prefab de UI de ejemplo
3. Reproducir hápticos

---

Añadir una descripción de uso de Bluetooth

Los dispositivos hápticos se comunican por Bluetooth, por lo que su aplicación necesita la clave NSBluetoothAlwaysUsageDescription. El bHaptics SDK no la añade automáticamente, así que debe añadirla usted mismo.

Si no la añade:

• La primera vez que su aplicación acceda a CoreBluetooth (por ejemplo, cuando el SDK inicializa su gestor de Bluetooth para reconectar los dispositivos emparejados, o cuando inicia una búsqueda), iOS cierra la aplicación de inmediato:

  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 validación de subida de App Store Connect puede rechazar la compilación con el error ITMS-90683 (Missing purpose string) incluso si su aplicación nunca llama a la API de búsqueda en tiempo de ejecución, porque la aplicación compilada hace referencia a APIs de CoreBluetooth.

Cómo añadir la descripción

En el proyecto de Xcode generado, seleccione el target principal de la aplicación (normalmente Unity-iPhone en una compilación para iOS) y abra la pestaña Info. Añada Privacy - Bluetooth Always Usage Description, o edite Info.plist directamente:

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

Redacte un texto específico de su aplicación que explique por qué usa Bluetooth. App Review puede rechazar un texto vago o genérico (directriz 5.1.1).

tip

La ventana emergente de permiso aparece la primera vez que se inicia la aplicación y muestra este texto. Use InfoPlist.strings para la localización.

Conectar con la UI de ejemplo

El prefab [bHapticsUIApple] es una UI de ejemplo que muestra cómo buscar y conectarse a dispositivos bHaptics, utilizando internamente la API BhapticsAppleDevices.

Use el prefab [bHapticsUIApple] solo para iOS/visionOS.

Requisito previo

Esta guía da por supuesto que ya ha importado el bHaptics Unity SDK y ha vinculado su aplicación háptica. Si no es así, consulte primero la Guía de Unity.

Añadir el prefab de UI

Coloque el prefab Assets/Bhaptics/SDK2/Prefabs/[bHapticsUIApple] en su escena.

Buscar dispositivos

• Al pulsar Scan se buscan los dispositivos bHaptics cercanos.
• La búsqueda se detiene automáticamente después de 30 segundos; el botón muestra una cuenta atrás del tiempo restante. Púlselo de nuevo para detener la búsqueda de inmediato.
• La lista muestra los dispositivos encontrados en esta búsqueda junto con los dispositivos emparejados previamente.

Conectar

• Al pulsar Connect en un dispositivo, este se empareja (se recuerda) y se conecta en un solo paso. El estado se vuelve verde y muestra Connected.
• Disconnect desempareja (olvida) el dispositivo y lo desconecta.

Cada dispositivo muestra su estado de conexión. Hay tres estados posibles:

Estado	Significado
[Position] - Connected (verde)	Conectado
[Position] - Paired (gris)	Recordado, pero no conectado actualmente
[Position]	Encontrado en la búsqueda, no emparejado

Las conexiones son por aplicación

La información de emparejamiento se almacena en el sandbox propio de la aplicación, no en el emparejamiento Bluetooth a nivel de sistema de la app Ajustes de iOS.

• Debe emparejar por separado en cada aplicación. Para usar el mismo dispositivo desde otra aplicación, conéctelo de nuevo desde esa aplicación.
• Una vez emparejado, el dispositivo se reconecta automáticamente la próxima vez que se inicialice el SDK (el prefab [bHaptics] se encarga de ello cuando su aplicación arranca).
• Un dispositivo que no haya emparejado nunca se conecta por sí solo: la búsqueda y el emparejamiento son siempre explícitos (útil para escenarios multiusuario y eventos presenciales).

Siguiente paso: reproducir hápticos

La búsqueda y la conexión funcionan por sí solas, pero para reproducir eventos es necesario que el SDK esté inicializado. De la inicialización se encarga el prefab [bHaptics]. Añádalo a su primera escena (consulte Add Prefab for Initialization en la Guía de Unity).

Con el prefab en su sitio, reproduzca los eventos como de costumbre:

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

Apéndice: controlarlo directamente sin la UI

[bHapticsUIApple] es solo un ejemplo: puede crear su propia UI de conexión con la misma API de bajo nivel. Consulte Class BhapticsAppleDevices en las Referencias.