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

• 即使您的应用在运行时从未调用扫描 API，App Store Connect 的上传校验也可能以 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] 预制体是一个示例 UI，演示如何扫描并连接 bHaptics 设备，其内部使用 BhapticsAppleDevices API。

请仅在 iOS/visionOS 上使用 [bHapticsUIApple] 预制体。

前置条件

本指南假定您已导入 bHaptics Unity SDK 并关联了触觉应用。如果尚未完成，请先参阅 Unity 指南。

添加 UI 预制体

将 Assets/Bhaptics/SDK2/Prefabs/[bHapticsUIApple] 预制体放置到您的场景中。

扫描

• 点按 Scan 会搜索附近的 bHaptics 设备。
• 扫描会在 30 秒后自动停止；按钮上会以倒计时显示剩余时间。再次点按可立即停止扫描。
• 列表中会同时显示本次扫描发现的设备和之前配对过的设备。

连接

• 在设备上点按 Connect 会一步完成配对（记住）和连接。状态会变为绿色并显示 Connected。
• Disconnect 会取消配对（忘记）该设备并断开连接。

每台设备都会显示其连接状态。共有三种可能的状态：

状态	含义
[Position] - Connected (绿色)	已连接
[Position] - Paired (灰色)	已记住，但当前未连接
[Position]	已扫描到，未配对

连接以应用为单位

配对信息存储在应用自己的沙盒中，而不是 iOS 设置应用中的系统级 Bluetooth 配对。

• 您必须在每个应用中分别配对。若要在另一个应用中使用同一台设备，请在该应用中重新连接。
• 一旦配对，设备会在下次 SDK 初始化时自动重新连接（应用启动时由 [bHaptics] 预制体完成此操作）。
• 未配对的设备绝不会自行连接 —— 扫描和配对始终是显式的（这对多用户、线下活动场景很有用）。

下一步：播放触觉

扫描和连接本身即可工作，但播放事件需要 SDK 已初始化。初始化由 [bHaptics] 预制体处理。请将它添加到您的第一个场景中（参阅 Unity 指南中的 Add Prefab for Initialization）。

放置好预制体后，即可像平常一样播放事件：

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

附录：不使用 UI 直接控制

[bHapticsUIApple] 只是一个示例 —— 您可以用同样的底层 API 构建自己的连接 UI。请参阅参考文档中的 Class BhapticsAppleDevices。