Unity용 iOS/visionOS 연결 가이드

적용 범위

bHaptics Unity SDK 2.8.0 이상, iOS 및 visionOS 실기기에만 적용됩니다. [bHapticsUIApple] 프리팹과 BhapticsAppleDevices API는 에디터나 다른 플랫폼에서는 아무 동작도 하지 않습니다. iOS/visionOS에서만 사용하고, 항상 실기기에서 테스트하세요.

Windows/macOS/Android에서는 bHaptics Player 앱이 기기 연결을 관리합니다. iOS/visionOS에서는 그럴 수 없는데, 앱 샌드박스가 한 앱이 다른 앱을 위해 Bluetooth 연결을 유지하는 것을 허용하지 않기 때문입니다. 대신 각 앱이 CoreBluetooth로 기기를 직접 스캔하고 연결합니다.

SDK는 BhapticsAppleDevices API와 샘플 UI 프리팹 [bHapticsUIApple]을 제공합니다. 아래 단계에서는 이 프리팹을 사용합니다.

1. Bluetooth 사용 설명 추가
2. 샘플 UI 프리팹으로 스캔 및 연결 관리
3. 햅틱 재생

---

Bluetooth 사용 설명 추가

햅틱 기기는 Bluetooth로 통신하므로, 앱에 NSBluetoothAlwaysUsageDescription 키가 필요합니다. bHaptics SDK는 이 키를 자동으로 추가하지 않으므로, 직접 추가해야 합니다.

추가하지 않으면:

• 앱이 CoreBluetooth에 처음 접근할 때(예: SDK가 페어링된 기기를 다시 연결하려고 Bluetooth 매니저를 초기화하거나 스캔을 시작할 때), iOS가 앱을 즉시 종료합니다:

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

• App Store Connect 업로드 검증은 앱이 런타임에 스캔 API를 전혀 호출하지 않더라도 ITMS-90683 (Missing purpose string) 오류로 빌드를 거부할 수 있습니다. 빌드된 애플리케이션이 CoreBluetooth API를 참조하기 때문입니다.

설명 추가 방법

생성된 Xcode 프로젝트에서 앱의 메인 타깃(iOS 빌드의 경우 일반적으로 Unity-iPhone)을 선택하고 Info 탭을 엽니다. Privacy - Bluetooth Always Usage Description을 추가하거나, 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>

앱이 Bluetooth를 사용하는 이유를 설명하는 앱 고유의 문구를 작성하세요. 모호하거나 일반적인 문구는 App Review에서 거부될 수 있습니다(가이드라인 5.1.1).

팁

이 문구는 권한 팝업에 표시됩니다. 현지화하려면 InfoPlist.strings를 사용하세요.

샘플 UI로 연결하기

[bHapticsUIApple] 프리팹은 bHaptics 기기를 스캔하고 연결하는 방법을 보여주는 샘플 UI로, 내부적으로 BhapticsAppleDevices API를 사용합니다.

[bHapticsUIApple] 프리팹은 iOS/visionOS에서만 사용하세요.

사전 준비

이 가이드는 bHaptics Unity SDK를 이미 가져오고 햅틱 앱을 연동했다고 가정합니다. 그렇지 않다면 먼저 Unity 가이드를 참고하세요.

UI 프리팹 추가

씬에 Assets/Bhaptics/SDK2/Prefabs/[bHapticsUIApple] 프리팹을 배치합니다.

스캔

• Scan을 누르면 주변의 bHaptics 기기를 검색합니다.
• Bluetooth 권한 팝업이 처음 한 번 표시됩니다(이전 단계에서 작성한 설명 문구가 표시됩니다).
• 스캔은 30초 후 자동으로 중지되며, 버튼에 남은 시간이 카운트다운으로 표시됩니다. 버튼을 다시 누르면 즉시 스캔을 중지합니다.
• 목록에는 이번 스캔에서 발견된 기기와 이전에 페어링한 기기가 함께 표시됩니다.

연결

• 기기에서 Connect를 누르면 페어링(기억)과 연결이 한 번에 이루어집니다. 상태가 초록색으로 바뀌고 Connected가 표시됩니다.
• Disconnect는 기기의 페어링을 해제(잊기)하고 연결을 끊습니다.

각 기기에는 연결 상태가 표시됩니다. 가능한 상태는 세 가지입니다:

상태	의미
[Position] - Connected (초록)	연결됨
[Position] - Paired (회색)	기억되어 있지만 현재 연결되지 않음
[Position]	스캔됨, 페어링 안 됨

연결은 앱 단위입니다

페어링 정보는 iOS 설정 앱의 시스템 수준 Bluetooth 페어링이 아니라 앱 자체의 샌드박스에 저장됩니다.

• 앱마다 각각 페어링해야 합니다. 다른 앱에서 같은 기기를 사용하려면 그 앱에서 다시 연결하세요.
• 한 번 페어링하면, 다음에 SDK가 초기화될 때 기기가 자동으로 다시 연결됩니다(앱이 시작될 때 [bHaptics] 프리팹이 이를 수행합니다).
• 페어링하지 않은 기기는 스스로 연결되지 않습니다 — 스캔과 페어링은 항상 명시적입니다(멀티 유저, 현장 이벤트에 유용).

다음 단계: 햅틱 재생

스캔과 연결은 초기화 없이도 동작하지만, 이벤트를 재생하려면 SDK가 초기화되어 있어야 합니다. 초기화는 [bHaptics] 프리팹이 처리합니다. 첫 번째 씬에 이 프리팹을 추가하세요(Unity 가이드의 초기화를 위한 프리팹 추가하기 참고).

프리팹을 배치했다면, 평소처럼 이벤트를 재생합니다:

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

부록: UI 없이 직접 제어하기

[bHapticsUIApple]은 샘플일 뿐입니다. 동일한 저수준 API로 직접 연결 UI를 만들 수 있습니다. 레퍼런스의 Class BhapticsAppleDevices를 참고하세요.