# CS 本地客户端唤起协议配置
平台支持通过自定义 URI 协议唤起用户电脑上的 CS 本地客户端。该能力不依赖特定客户端,可配置 myapp://、myapp://open?id=123、client:start 等协议地址。
平台只保存和调用协议,不读取或修改用户电脑的本地配置。
# 平台配置
在“服务集成 > 应用拓展 > 添加”中选择:
| 配置项 | 示例 |
|---|---|
| 应用类型 | CS本地客户端 |
| 应用名称 | 示例客户端 |
| 唤起协议 | myapp:// |
应用类型以 IAM 返回的 config.appType 为准:
CS:CS 本地客户端。BS:网页应用。- 缺失或未知:按历史 BS 应用处理。
保存后,用户可以从应用卡片或配置后的菜单入口点击应用。页面会展示应用名称和协议,等待 0.5 秒后调用系统协议,并显示 5 秒等待倒计时。如果客户端未打开,页面会提示检查客户端安装和本地协议配置。
# Windows 配置
Windows 通过注册表登记协议处理器。
# 当前用户配置
以 myapp:// 为例,新建 myapp.reg:
Windows Registry Editor Version 5.00
[HKEY_CURRENT_USER\Software\Classes\myapp]
@="URL:My App Launcher"
"URL Protocol"=""
[HKEY_CURRENT_USER\Software\Classes\myapp\shell]
[HKEY_CURRENT_USER\Software\Classes\myapp\shell\open]
[HKEY_CURRENT_USER\Software\Classes\myapp\shell\open\command]
@="\"C:\\Path\\To\\ExampleApp.exe\" \"%1\""
其中:
myapp:协议名称,必须与平台配置一致。C:\Path\To\ExampleApp.exe:实际客户端路径。%1:浏览器传入的完整协议地址。
双击导入,或执行:
reg import myapp.reg
需要所有用户生效时,可由管理员写入 HKEY_LOCAL_MACHINE\Software\Classes\myapp。
# 验证
Start-Process "myapp://"
系统弹出打开确认后,客户端应正常启动。
# macOS 配置
macOS 没有注册表,应用通过 Info.plist 中的 CFBundleURLTypes 声明协议,并由 LaunchServices 管理。
# 客户端声明协议
在客户端 .app/Contents/Info.plist 中增加:
<key>CFBundleURLTypes</key>
<array>
<dict>
<key>CFBundleURLName</key>
<string>com.example.myapp-launcher</string>
<key>CFBundleURLSchemes</key>
<array>
<string>myapp</string>
</array>
</dict>
</array>
# 使用 Helper App
客户端本身不支持协议时,可以提供已签名的 Helper App:
MyLauncher.app/
└── Contents/
├── Info.plist
└── MacOS/
└── MyLauncher
Helper App 负责声明协议,并在收到协议后启动实际客户端。正式分发时应使用 Developer ID 签名并公证。
# 注册到 LaunchServices
安装或更新应用后执行:
/System/Library/Frameworks/CoreServices.framework/Frameworks/LaunchServices.framework/Support/lsregister \
-f "/Applications/MyLauncher.app"
# 验证
检查协议声明:
plutil -p "/Applications/MyLauncher.app/Contents/Info.plist" | grep -A 8 CFBundleURLTypes
测试唤起:
open "myapp://"
# Windows 与 macOS 对比
| 项目 | Windows | macOS |
|---|---|---|
| 注册位置 | 注册表 | App 的 Info.plist |
| 协议声明 | HKEY_CURRENT_USER\Software\Classes\myapp | CFBundleURLSchemes = myapp |
| 启动配置 | shell\open\command | Helper App 或客户端执行文件 |
| 系统组件 | Registry | LaunchServices |
| 验证命令 | Start-Process "myapp://" | open "myapp://" |
# 常见问题
# 点击后没有反应
依次检查:
- 平台配置的协议与本地注册的 Scheme 是否一致。
- Windows 注册表是否已导入。
- macOS 应用是否包含正确的
CFBundleURLTypes。 - 客户端程序路径是否存在。
- 浏览器是否拦截了自定义协议。
- 当前用户是否有权限启动客户端。
# 正常协议会跳转,不存在的协议没有反应
这是浏览器行为:
- 已注册协议交给操作系统处理,页面通常会跳转到本地应用。
- 未注册协议可能被浏览器静默忽略或抛出异常。
平台页面会保留 5 秒等待倒计时,随后显示安装和协议配置提示。
# 浏览器首次打开时出现确认框
这是正常安全机制。用户确认后,部分浏览器可以记住该选择。
# 安全要求
- 协议名称建议使用小写字母,例如
myapp。 - 不要使用
http、https、file、javascript等系统保留或危险协议。 - Windows 注册表配置和 macOS Helper App 应由客户端安装包或企业 IT 统一部署。
- 不在协议参数中传递密码、令牌等敏感信息。
- 平台无法确认本地客户端是否真正启动,5 秒提示仅用于引导排查。