了解 AccessorySetupKit

了解 AccessorySetupKit

使用 AccessorySetupKit 提升你的配件设置体验。呈现精美的配对对话框，并在其中显示你的蓝牙或 Wi-Fi 配件的图像 — 无需访问“设置”App 就能实现。探索如何通过只将你的 App 与一个配件配对来加强隐私保护。此外，了解如何迁移现有配件，以便通过 AccessorySetupKit 进行管理。

资源
下载

大家好！我是 Yixin 来自 Apple 的 Bluetooth 团队
今天我很高兴向大家介绍如何使用 AccessorySetupKit 获得更好的配件设置体验我们首先会进行简要概述
然后深入了解 API 并一起创建一个示例 App
最后我们将讨论如何在配件选择器中让你的配件呈现出色效果
让我们从概述开始
配件是我们生活中极其重要的一部分包括监测健康状况的健身追踪器以及将艺术构想变为现实的创意工具在 iOS 18 和 iPadOS 18 中我们创建了一些功能来帮助你更好地设置配件
AccessorySetupKit 是一个全新框架可为 App 提供一种简化且保障隐私的方法用于设置和管理带有蓝牙和 Wi-Fi 的配件
只需调用某个 API 就会显示全新的配件选择器其中列出了附近所有可供你的 App 配对的配件你会在选择器中看到自己配件的高保真图案和友好名称
只需轻点一下配件就能与你的 App 安全配对并随时可供使用完成这一轻点操作后便可以通过你的配件访问蓝牙和 Wi-Fi 前提是配件支持蓝牙和 Wi-Fi
App 可继续使用相同的 CoreBluetooth 和 NetworkExtension API 与配件进行通信
在“隐私与安全性”设置中 “配件”行是通过 AccessorySetupKit 管理的所有配件的新位置在每个配件的详情页面中你的产品图像、显示名称和硬件名称可帮助用户轻松识别配件
用户可以修改配件名称切换已配对 App 的访问权限或将配件从系统中移除
新设计的配件页面还可以在 “蓝牙设置”和“Wi-Fi 设置”中找到具体位置取决于你的配件支持的技术
在 iOS 18 和 iPadOS 18 中 AccessorySetupKit 支持蓝牙和 Wi-Fi 配件那么它是如何工作的呢我们先了解一下 App 过去如何设置配件以及 AccessorySetupKit 与过去的做法相比有什么不同
以前 App 需要请求获得蓝牙使用权限才能发现并连接到任一配件
App 需要另行请求加入配件正在广播的 Wi-Fi 网络
另外可能还有额外的蓝牙配对请求相比之下 AccessorySetupKit 为你和你的顾客消除了所有障碍只需点按一下配件就会与你的 App 配对并向你的 App 授予蓝牙和 Wi-Fi 访问权限在新的配件选择器中用户比以往更容易知晓自己允许使用的是什么配件因为选择器会显示配件的友好名称和产品图像以及配件通过无线方式广播的硬件名称这样用户就可以先确保配件真实性然后再轻点进行设置这一切都得益于 AccessorySetupKit 保障隐私的设计
你的 App 上显示的配件选择器在单独的进程中运行你的 App 会将发现规则和素材发送给选择器进程这些规则可以配置为同时具有蓝牙和 Wi-Fi 接口因此你可以在一个设置流程中获得配件的所有必要通信访问权限
一旦发现配件就会出现在选择器中只需轻点一下就能与你的 App 配对
以上就是 AccessorySetupKit 的概述现在我们深入了解一下 API 我们将构建一个 App 用于设置数字骰子并通过蓝牙同步掷骰子结果你也可以下载示例项目数字骰子由使用 CoreBluetooth 的 App 模拟我们的示例 App 将与它连接并订阅它的蓝牙 GATT 服务
为了使用 AccessorySetupKit 我们将在 App 的 Info.plist 中添加几个条目我们将把 Bluetooth 放在 AccessorySetupKit - Supports 下因为这是我们的示例 App 与骰子通信的方式 Wi-Fi 是这个数组中另一个受支持的项目然后我们将为配件的发现添加规则无论是 Bluetooth Services、 Wi-Fi SSIDs 还是 Company Identifiers 由于我们的骰子有 2 种颜色变体而且每种变体都广播不同的服务 UUID 因此我们将这 2 个 UUID 放在 Bluetooth Services 下现在要在 App 中使用配件有 3 个步骤分别是发现配件授权使用配件以及与配件通信 AccessorySetupKit 负责发现和授权而通信仍由 CoreBluetooth 和 NetworkExtension 处理就像以前的 iOS 版本一样
我们在 AccessorySetupKit 中遇到的第一个类是 ASAccessorySession
这是一个中心对象用于显示配件选择器、发送事件通知以及管理配件
当我们要求 ASAccessorySession 显示选择器时我们会提供一个 ASPickerDisplayItem 对象数组
ASPickerDisplayItem 定义配件的名称和图像以及一个发现描述符用于告诉系统如何扫描配件
有了这些我们就可以在 ASAccessorySession 上调用 showPicker 以开始选择器进程的发现和授权操作设置完成后 App 将通过会话对象收到 ASAccessoryEvent 这个事件包含关于新添加配件的重要信息以便 App 与配件交互
现在让我们编写一些代码
正如前面提到的我们首先要创建一个 ASAccessorySession
这个会话将使用 DispatchQueue 和 eventHandler 进行激活前者表示执行 API 调用的位置后者供 App 用于处理来自这个会话的事件
每当会话、配件或选择器有更新时 ASAccessoryEvent 就会传递给事件处理程序由于事件多种多样你可以通过检查 eventType 来进行区分使用 activated 事件作为信号允许你通过读取会话中的 “accessories”属性来查询配件或启动新的设置流程稍后我们将进一步讨论事件处理现在让我们学习如何通过创建选择器显示项目并调用配件选择器来启动设置流程
创建显示项目需要产品名称、产品图像和发现描述符通过 ASDiscoveryDescriptor 类你可以将所有必要的发现规则合并为一个复合对象系统会将扫描结果与描述符内的所有规则进行匹配以筛选出你关注的确切配件 ASDiscoveryDescriptor 非常灵活有许多可自定的字段如蓝牙服务 UUID 和 Wi-Fi SSID 请参阅 developer.apple.com/cn 上的文档了解所有相关信息
要发现我们的骰子发现描述符需要将它的 bluetoothServiceUUID 设置为骰子广播的 GATT 服务 UUID
由于粉色骰子和蓝色骰子根据自身颜色来广播不同的服务 UUID 因此我们需要使用各自的服务 UUID 为每种颜色创建不同的发现描述符
然后我们传入骰子的名称、图像和相应的发现描述符以便为这两种颜色变体的骰子创建显示项目这样系统就可以将这两种颜色变体作为单独的配件进行扫描
你可以使用 ASPickerDisplayItem 的更多属性来自定设置体验请务必查看我们的文档最后我们在示例 App 中设置了一个按钮只需在激活的会话中调用 showPicker 同时传入我们为粉色骰子和蓝色骰子创建的显示项目即可这时配件选择器就会显示并开始发现和设置进程让我们开始吧
在桌面上我有一台模拟粉色骰子的手机在我们的示例 App 中如果我们轻点“Add”按钮配件选择器就会滑出并覆盖在 App 上粉色骰子会立即被发现并显示现在如果我再用另一台模拟手机打开我的蓝色骰子就会看到骰子被发现并以动画形式从屏幕边缘闪现选择器会创建一个水平轮播界面用于放置配件的精美素材我们可以左右轻扫来选择这次要设置的骰子它们看起来都很可爱但我们都喜欢亮粉色让我们设置粉色骰子吧连接...完成粉色骰子现在可以通过我们的 App 使用了就是这么快
如果你的配件需要更安全的配对方法如数字比较和通行密钥输入配件选择器会显示各种蓝牙配对 UI 现在粉色骰子已经设置好了接下来呢
当配件可以使用时 App 会收到 accessoryAdded 事件通过读取这个事件中的 accessory 属性我们会得到一个 ASAccessory 对象代表我们新设置的骰子其他一些事件包括 accessoryChanged 这个事件在配件属性更改时发送例如显示名称可以在 “设置”中进行更改当用户或 App 从系统中移除配件时就会发送 accessoryRemoved
ASAccessory 类代表一个物理配件它包含配件的授权状态显示名称、发现描述符以及配件的所有网络接口包括 CBPeripheral 的蓝牙标识符如果配件广播 Wi-Fi 网络那么还包括 Wi-Fi SSID 通过 accessoryAdded 事件中的 ASAccessory 对象我们可以使用 CoreBluetooth 连接到蓝牙外设
我们将像往常一样创建 CBCentralManager 由于我们在 Info.plist 中声明了对 AccessorySetupKit 的支持因此与以前版本的 iOS 不同 App 不会询问用户是否允许使用蓝牙
CBCentralManager 状态只有在 App 与配件配对后才会开启在我们的例子中粉色骰子已与 AccessorySetupKit 配对我们将使用 bluetoothIdentifier 获取粉色骰子的蓝牙外设当然你也可以使用中央管理器的扫描 API 来扫描外设扫描结果只会返回已与 App 配对的配件然后我们将连接到外设连接成功后就会发现它的 GATT 服务这样我们就可以读取更新并获得更新通知
如果你是初次使用 App 连接蓝牙配件请查阅 developer.apple.com/cn 上的 CoreBluetooth 文档了解更多详情说了这么多让我们尝试连接到新设置的粉色骰子吧
我们可以从示例 App 连接到骰子模拟器让我们拿出模拟器 App 开始掷骰子吧
很好掷骰子的结果会实时同步到我们的示例 App 中我们就是这样使用 AccessorySetupKit 来设置配件然后使用现有的网络 API 来连接配件但是如果你的 App 已获得授权从而可以使用蓝牙来管理现有配件而无需使用 AccessorySetupKit 该怎么办呢 App 如何从这个权限模型过渡到 AccessorySetupKit 中更精细的模型呢
使用现有配件的蓝牙外设标识符或 Wi-Fi SSID 你可以创建 ASMigrationDisplayItem 的实例它是 ASPickerDisplayItem 的子类将这些迁移项传递给 showPicker 调用从而将现有配件升级为由 AccessorySetupKit 进行管理并在新的配件设置中找到它们如果 showPicker 调用只包含迁移项目则会在 App 上显示一个信息页面向用户通知迁移情况请注意如果你选择将迁移项与其他非迁移显示项一起传递迁移只会在发现并设置新配件时进行
这就是如何迁移现有配件以便由 AccessorySetupKit 进行管理的方法在我们结束今天的讲座之前我想与大家分享一些推荐的设计实践这些实践能够真正提升你的配件设置体验
配件选择器提供一个 180 x 120 磅值大小的容器框用于放置产品图像确保你的图像有足够的像素分辨率以便在各种缩放系数的屏幕上都能清晰显示
务必在浅色和深色两种模式下测试素材效果图像背景应该是透明的以便在两种模式下看起来都很美观
利用图像周围的透明边框当系统将整个图像缩放到容器框中时透明边框越宽屏幕上显示的配件就越小通过调整透明边框来实现内边距的效果在选择器 UI 中获得大小完美的图像
请记住在用户设置配件时 App 的部分 UI 会被配件选择器遮挡住不要进行在设置过程中可能导致 UI 不可见的更新你可以侦听 pickerDidPresent 和 pickerDidDismiss 事件以跟踪选择器的显示和关闭
最后但也同样重要的是虽然 showPicker API 随时可以调用但为避免意外显示选择器我们建议在显示选择器之前向用户展示足够多的关于添加新配件的上下文如果可能的话将 showPicker 调用绑定到一个按钮上这样设置体验就始终由用户启动了
最后我想重申今天讲座的几个要点 AccessorySetupKit 是设置蓝牙和 Wi-Fi 配件的全新方法只需点按一下 App 就能同时通过蓝牙和 Wi-Fi 访问配件在用户初次体验你的产品这一关键时刻这项功能可最大限度地降低给客户带来的不便
使用时请在 App 的 Info.plist 中添加 AccessorySetupKit 项目创建 ASAccessorySession 并等待它激活以启动任务为每个要发现的配件创建一个 ASPickerDisplayItem 显示配件选择器以启动设置过程并对事件作出适当响应如果 App 已经使用系统访问权限来管理现有配件请使用 ASMigrationDisplayItem 将配件迁移至 AccessorySetupKit 注意素材的设计确保配件在配件选择器内以最佳方式展示给顾客
感谢观看

import AccessorySetupKit

// Create a session
var session = ASAccessorySession()

// Activate session with event handler
session.activate(on: DispatchQueue.main, eventHandler: handleSessionEvent(event:))

// Handle event
func handleSessionEvent(event: ASAccessoryEvent) {  
    switch event.eventType {
    case .activated:
        print("Session is activated and ready to use")
        print(session.accessories)
    default:
        print("Received event type \(event.eventType)")
    }
}

7:23 - Create picker display items

// Create descriptor for pink dice
let pinkDescriptor = ASDiscoveryDescriptor()
pinkDescriptor.bluetoothServiceUUID = pinkUUID
// Create descriptor for blue dice
let blueDescriptor = ASDiscoveryDescriptor()
blueDescriptor.bluetoothServiceUUID = blueUUID

// Create picker display items
let pinkDisplayItem = ASPickerDisplayItem(
    name: "Pink Dice",
    productImage: UIImage(named: "pink")!,
    descriptor: pinkDescriptor
)
let blueDisplayItem = ASPickerDisplayItem(
    name: "Blue Dice",
    productImage: UIImage(named: "blue")!,
    descriptor: blueDescriptor
)

8:10 - Show picker

// Invoke accessory picker
Button {
    session.showPicker(for: [pinkDisplayItem, blueDisplayItem]) { error in
        if let error {
            // Handle error
        }
    }
} label: {
    Text("Add Dice")
}

9:26 - Handle events

// Handle event
func handleSessionEvent(event: ASAccessoryEvent) {  
    switch event.eventType {

    case .accessoryAdded:
        let newDice: ASAccessory = event.accessory!

    case .accessoryChanged:
        print("Accessory properties changed")

    case .accessoryRemoved:
        print("Accessory removed from system")

    default:
        print("Received event with type: \(event.eventType)")
    }
}

10:22 - Communicate with accessory

// Connect to accessory using CoreBluetooth
let central = CBCentralManager(delegate: self, queue: nil)

func centralManagerDidUpdateState(_ central: CBCentralManager) {
    switch central.state {
    case .poweredOn:
       // state will only be updated to poweredOn when you have paired accessories
        let peripheral = central.retrievePeripherals(withIdentifiers: [newDice.bluetoothIdentifier]).first
        central.connect(peripheral)
    default:
        print("Received event type \(event.eventType)")
    }
}

func centralManager(_ central: CBCentralManager, didConnect peripheral: CBPeripheral) {
    peripheral.delegate = self
    peripheral.discoverServices(pinkUUID)
}

11:58 - Migrate existing accessories

// Create migration items
let pinkMigration = ASMigrationDisplayItem(name: "Pink Dice", productImage: UIImage(named: "pink")!, descriptor: pinkDescriptor)
pinkMigration.peripheralIdentifier = pinkPeripheral.identifier

// Present picker with migration items
session.showPicker(for: [pinkMigration]) { error in
    if let error {
        // Handle error
    }
}

正在查找特定内容？在上方输入一个主题，就能直接跳转到相应的精彩内容。

提交你查询的内容时出现错误。请检查互联网连接，然后再试一次。

资源