Virtuoz iOS SDK

Virtuoz iOS SDK 使您能够将 Virtuoz 体验集成到您的原生 iOS 和 iPadOS 应用中。

这个 Swift 库会在用户点击 Virtuoz 时通知您，并允许您根据需要触发设备上的振动。

• Virtuoz iOS SDK
  • 🚀 快速开始
    • 安装
      • Swift Package Manager
      • XCFramework
    • 一次性设置
      • 初始化 SDK
      • 配置 SDK
    • 用法
      • 监听事件
      • 触发操作
  • 🎬 示例
  • 📄 许可协议

将 Virtuoz iOS SDK 包添加到您的应用程序。 有几种支持的安装选项。

将 Swift 包作为依赖项添加到 Xcode 项目中

1. 在 Xcode 中，打开您的项目并导航至 File → Add Packages…（文件 → 添加包…）
2. 输入包 URL https://github.com/MagieFactory/virtuoz-sdk
3. 对于 Dependency Rule（依赖规则），选择 Up to Next Major Version（直到下一个主版本）
4. 点击 Add Package（添加包）

或者，如果您的项目有一个 Package.swift 文件，您可以将 Virtuoz iOS SDK 添加到您的依赖项中

dependencies: [
    .package(url: "https://github.com/MagieFactory/virtuoz-sdk", from: "1.0.0"),
]

每个 发行版 都附带一个 XCFramework。

1. 下载附加到 最新发行版 的 VirtuozSDK.xcframework.zip 并解压缩。
2. 在 Xcode 中，打开您的项目并导航至 File → Add Files to "<Project>"…（文件 → 将文件添加到“<项目>”…）
3. 在文件导航器中找到 XCFramework 并选择它
4. 确保选中“Copy items if needed”（如果需要则复制项目）选项，并且已选择您的应用程序目标
5. 点击 Add（添加）
6. 在项目导航器中选择您的项目，选择您的应用目标，然后选择 General（通用）选项卡。 在 Frameworks, Libraries, and Embedded Content（框架、库和嵌入的内容）下，将 VirtuozSDK.xcframework 设置为 Embed & Sign（嵌入并签名）

安装软件包后，您可以通过使用 import VirtuozSDK 导入包来引用 Virtuoz iOS SDK。

Virtuoz iOS SDK 实例可以随时使用（在后台，单例模式确保只存在一个实例）。 将 Virtuoz 链接到您的应用需要遵循几个步骤。

1. 如果尚未为您的应用创建自定义 URL scheme，请创建一个。 SDK 使用此 scheme 来处理 Virtuoz 和您的应用之间的导航。 您可以在 Apple 网站上找到 教程
2. Virtuoz SDK 必须处理 application(_ app: UIApplication, open url: URL, options: [UIApplication.OpenURLOptionsKey : Any] = [:]) -> Bool 方法中的 fallback URL。

func application(_ app: UIApplication, open url: URL, options: [UIApplication.OpenURLOptionsKey : Any] = [:]) -> Bool {
   return VirtuozManager.shared.handleUrl(url)
}

设置 SDK 后，您需要根据需要配置它。

let configuration = VirtuozSDK.Configuration(urlScheme: "YOUR_URL_SCHEME://", enableLogs: true, killAppOnLongPress: false)
VirtuozManager.shared.setup(with: configuration)

Configuration 结构体允许您自定义 VirtuozSDK 如何处理各种选项

• urlScheme 必须与 初始化 SDK 部分中定义的值匹配。
• enableLogs 控制控制台中的调试日志记录。 您可以在生产环境中禁用此功能。
• killAppOnLongPress 告诉 Virtuoz SDK 在用户长按 Virtuoz 时自动关闭应用程序。

接下来，调用 connect 方法以启动 Virtuoz 和您的应用程序之间的配对。

VirtuozManager.shared.connect(onSuccess: {
	print("✅ Connection with Virtuoz app is complete!")
}, onError: { 
	print("🚫 There was an error while linking your app 😢")
})

将一个类符合 VirtuozManagerDelegate 协议会在 Virtuoz 上发生事件时通知您。

VirtuozManager.shared.delegate = self

以下是委托方法的列表

• virtuozHasBeenUnpaired() 在 Virtuoz 从 Virtuoz 应用取消配对时通知您。
• virtuozStateUpdated(state: VirtuozSDK.PeripheralState) 在 Virtuoz 连接或断开连接时通知您。
• virtuozHasAnUpdateAvailable() 在 Virtuoz 更新可用时通知您。 然后，您可以使用 VirtuozManager 实例中的 redirectToVirtuoz() 方法重定向到 Virtuoz。
• virtuozBatteryLevelUpdated(value: Int, image: UIImage?) 在电池电量变化时通知您（及其相应的状态图像）。
• virtuozDidPress() 在按下 Virtuoz 时通知您。
• virtuozDidLongPress() 在长按 Virtuoz 时通知您。

您可以在 Example 文件夹中的演示应用程序中看到所有这些委托方法的实现。

通过同一个 VirtuozManager 实例访问信息并在您的应用中触发操作。

• linkedVirtuozName 返回当前链接的 Virtuoz 设备的名称。
• redirectToVirtuoz() 必要时打开 Virtuoz 应用。
• triggerVibration() 向连接的 Virtuoz 设备发送立即振动命令。

存储库中的 Example 目录包含完整的示例 iOS 应用程序，演示了如何在项目中集成 Virtuoz SDK。

本项目采用 MIT 许可证。 有关详细信息，请参阅 LICENSE。