【V3】How to configure the custom protocol for v3? I reported an error after configuring it

[zk3151463]

Description

v3 怎么配置自定义协议呢，我配置后报错(How to configure the custom protocol for v3? I reported an error after configuring it)

To Reproduce

How to configure the custom protocol for v3? I reported an error after configuring it

Expected behaviour

How to configure the custom protocol for v3? I reported an error after configuring it

Screenshots

Attempted Fixes

No response

System Details

System 

┌─────────────────────────────────────────────────┐
| Name          | MacOS                           |
| Version       | 15.6                            |
| ID            | 24G84                           |
| Branding      | Sequoia                         |
| Platform      | darwin                          |
| Architecture  | arm64                           |
| Apple Silicon | true                            |
| CPU           | Apple M1                        |
| CPU 1         | Apple M1                        |
| CPU 2         | Apple M1                        |
| GPU           | 8 cores, Metal Support: Metal 3 |
| Memory        | 16 GB                           |
└─────────────────────────────────────────────────┘

# Build Environment 

┌─────────────────────────────────────────────────────────────────────────────────────────────────────┐
| Wails CLI      | v3.0.0-alpha.26                                                                    |
| Go Version     | go1.25.0                                                                           |
| -buildmode     | exe                                                                                |
| -compiler      | gc                                                                                 |
| CGO_ENABLED    | 0                                                                                  |
| DefaultGODEBUG | containermaxprocs=0,decoratemappings=0,tlssha1=1,updatemaxprocs=0,x509sha256skid=0 |
| GOARCH         | arm64                                                                              |
| GOARM64        | v8.0                                                                               |
| GOOS           | darwin                                                                             |
└─────────────────────────────────────────────────────────────────────────────────────────────────────┘

# Dependencies 

┌───────────────────────────┐
| Xcode cli tools | 2410    |
| npm             | 10.8.2  |
| *NSIS           | v3.11   |
|                           |
└─ * - Optional Dependency ─┘

Additional context

No response

[github-actions]

👋 Thanks for reporting this issue! To help us investigate, could you please:

1. Add the output of wails doctor if not already included
2. Provide clear steps to reproduce the issue
3. If possible, create a minimal reproduction of the issue

This will help us resolve your issue much faster. Thank you!

[dosubot]

Hi @zk3151463! I'm Dosu and I’m helping the wails team.

To configure a custom protocol in Wails v3, add a protocols array under the info section in your wails.json file. Each protocol should have a scheme (like "wbxnkai"), and optionally a description (Windows only) and role (macOS only). For example:

{
  "info": {
    "protocols": [
      {
        "scheme": "wbxnkai",
        "description": "My Custom Protocol",
        "role": "Editor"
      }
    ]
  }
}

Only the properties scheme, description, and role are supported—extra fields (like "My Other Data") will cause errors. Make sure your config matches the documented structure exactly see docs.

After updating your config, run task common:update:build-assets and then build/package your app with task package for the changes to take effect.

On macOS, handle incoming URLs by listening for the ApplicationLaunchedWithUrl event in your Go code:

app.OnApplicationEvent(events.Common.ApplicationLaunchedWithUrl, func(e *application.ApplicationEvent) {
   launchedURL := e.Context().URL()
   log.Printf("Application launched with URL: %s", launchedURL)
})

If you still see errors, double-check your config for typos or unsupported fields, and ensure you are using the latest alpha with custom protocol support fully merged. If possible, share the exact error message for more targeted help.

To reply, just mention @dosu.

---

^{How did I do? Good | Irrelevant | Incorrect | Verbose | Hallucination | Report 🐛 | Other}    

[zk3151463]

你好@zk3151463！我是Dosu，我正在帮助哀号队。

要在 Wails v3 中配置自定义协议，请在文件中的相应部分protocols下添加一个数组。每个协议都应该包含一个（例如），以及可选的（仅限 Windows）和（仅限 macOS）。例如：info``wails.json``scheme``"wbxnkai"``description``role

{
"info": {
"protocols": [
{
"scheme": "wbxnkai",
"description": "My Custom Protocol",
"role": "Editor"
}
]
}
}
仅支持属性scheme、description和—— 额外的字段（例如）将导致错误。请确保您的配置与文档中所述的结构完全匹配，请参阅文档。role``"My Other Data"

更新配置后，运行task common:update:build-assets并构建/打包您的应用程序以使task package更改生效。

在 macOS 上，通过监听ApplicationLaunchedWithUrlGo 代码中的事件来处理传入的 URL：

app.OnApplicationEvent(events.Common.ApplicationLaunchedWithUrl, func(e *application.ApplicationEvent) {
launchedURL := e.Context().URL()
log.Printf("Application launched with URL: %s", launchedURL)
})
如果仍然出现错误，请仔细检查您的配置，查看是否存在拼写错误或不支持的字段，并确保您使用的是最新的 Alpha 版本，并且自定义协议支持已完全合并。如果可能，请分享具体的错误信息，以便我们为您提供更有针对性的帮助。

要回复，只需提及@dosu。

我做得怎么样？好|不相关|不正确|冗长|幻觉|举报🐛 |其他    

v3 没有 wails.json 它的配置在 config.yml 中（In Wails v3, there is no wails.json; its configuration is located in config.yml.）

[dosubot]

感谢你的指正，Wails v3 的确是用 config.yml 而不是 wails.json。

自定义协议的配置结构保持不变，只是格式变成了 YAML。正确的 config.yml 示例如下：

info:
  protocols:
    - scheme: wbxnkai
      description: My Custom Protocol
      role: Editor

只支持 scheme、description（仅 Windows）、role（仅 macOS）这三个字段，不能有其他字段（比如 My Other Data），否则会报错。配置完成后，务必运行 task common:update:build-assets，然后用 task package 重新打包应用，才能生效。

macOS 下处理协议 URL 推荐用如下 Go 代码：

app.OnApplicationEvent(events.Common.ApplicationLaunchedWithUrl, func(e *application.ApplicationEvent) {
   launchedURL := e.Context().URL()
   log.Printf("Application launched with URL: %s", launchedURL)
})

详细文档和平台差异可参考 官方指南。

如还有报错，建议贴出具体错误信息，方便进一步定位。

To reply, just mention @dosu.

---

^{How did I do? Good | Irrelevant | Incorrect | Verbose | Hallucination | Report 🐛 | Other}    

[zk3151463]

感谢你的指正，Wails v3 的确是用 config.yml 而不是 wails.json。

自定义协议的配置结构保持不变，只是格式变成了 YAML。正确的 config.yml 示例如下：

info:
protocols:
- scheme: wbxnkai
description: My Custom Protocol
role: Editor
只支持 scheme、description（仅 Windows）、role（仅 macOS）这三个字段，不能有其他字段（比如 My Other Data），否则会报错。配置完成后，务必运行 task common:update:build-assets，然后用 task package 重新打包应用，才能生效。

macOS 下处理协议 URL 推荐用如下 Go 代码：

app.OnApplicationEvent(events.Common.ApplicationLaunchedWithUrl, func(e *application.ApplicationEvent) {
launchedURL := e.Context().URL()
log.Printf("Application launched with URL: %s", launchedURL)
})
详细文档和平台差异可参考 官方指南。

如还有报错，建议贴出具体错误信息，方便进一步定位。

To reply, just mention @dosu.

How did I do? Good | Irrelevant | Incorrect | Verbose | Hallucination | Report 🐛 | Other    

but this will cause an error : ERROR template: desktop.tmpl:14:43: executing "desktop.tmpl" at <.Info.Protocols>: can't evaluate field Info in type commands.UpdateConfig

[atterpac]

This is likely an error in what our asset generation expects the config file to look like

Looking into it.