# 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://"

# 常见问题

# 点击后没有反应

依次检查:

  1. 平台配置的协议与本地注册的 Scheme 是否一致。
  2. Windows 注册表是否已导入。
  3. macOS 应用是否包含正确的 CFBundleURLTypes。
  4. 客户端程序路径是否存在。
  5. 浏览器是否拦截了自定义协议。
  6. 当前用户是否有权限启动客户端。

# 正常协议会跳转,不存在的协议没有反应

这是浏览器行为:

  • 已注册协议交给操作系统处理,页面通常会跳转到本地应用。
  • 未注册协议可能被浏览器静默忽略或抛出异常。

平台页面会保留 5 秒等待倒计时,随后显示安装和协议配置提示。

# 浏览器首次打开时出现确认框

这是正常安全机制。用户确认后,部分浏览器可以记住该选择。

# 安全要求

  • 协议名称建议使用小写字母,例如 myapp。
  • 不要使用 http、https、file、javascript 等系统保留或危险协议。
  • Windows 注册表配置和 macOS Helper App 应由客户端安装包或企业 IT 统一部署。
  • 不在协议参数中传递密码、令牌等敏感信息。
  • 平台无法确认本地客户端是否真正启动,5 秒提示仅用于引导排查。