[V3] Add universal link support for macOS

[APshenkin]

Description

This PR backports https://github.com/wailsapp/wails/pull/4693/files to V3

Fixes # (issue)

Type of change

Please select the option that is relevant.

• Bug fix (non-breaking change which fixes an issue)
• New feature (non-breaking change which adds functionality)
• Breaking change (fix or feature that would cause existing functionality to not work as expected)
• This change requires a documentation update

How Has This Been Tested?

Please describe the tests that you ran to verify your changes. Provide instructions so we can reproduce. Please also list any relevant details for your test configuration using wails doctor.

• Windows
• macOS
• Linux

If you checked Linux, please specify the distro and version.

Test Configuration

# System

┌──────────────────────────────────────────────────┐
| Name          | MacOS                            |
| Version       | 26.1                             |
| ID            | 25B78                            |
| Branding      | MacOS 26.1                       |
| Platform      | darwin                           |
| Architecture  | arm64                            |
| Apple Silicon | true                             |
| CPU           | Apple M4 Max                     |
| CPU 1         | Apple M4 Max                     |
| CPU 2         | Apple M4 Max                     |
| GPU           | 40 cores, Metal Support: Metal 4 |
| Memory        | 128 GB                           |
└──────────────────────────────────────────────────┘

# Build Environment

┌─────────────────────────────────────────────────────────┐
| Wails CLI    | v3.0.0-dev                               |
| Go Version   | go1.24.0                                 |
| Revision     | 4a445ce218b58db4a16ee8fa84eac0d7c9a69932 |
| Modified     | false                                    |
| -buildmode   | exe                                      |
| -compiler    | gc                                       |
| CGO_CFLAGS   |                                          |
| CGO_CPPFLAGS |                                          |
| CGO_CXXFLAGS |                                          |
| CGO_ENABLED  | 1                                        |
| CGO_LDFLAGS  |                                          |
| GOARCH       | arm64                                    |
| GOARM64      | v8.0                                     |
| GOOS         | darwin                                   |
| vcs          | git                                      |
| vcs.modified | false                                    |
| vcs.revision | 4a445ce218b58db4a16ee8fa84eac0d7c9a69932 |
| vcs.time     | 2025-08-04T22:42:25Z                     |
└─────────────────────────────────────────────────────────┘

# Dependencies

┌────────────────────────────────────────────────────────────────────────┐
| Xcode cli tools | 2416                                                 |
| npm             | 10.9.2                                               |
| *NSIS           | Not Installed. Install with `brew install makensis`. |
|                                                                        |
└─────────────────────── * - Optional Dependency ────────────────────────┘

Please paste the output of wails doctor. If you are unable to run this command, please describe your environment in as much detail as possible.

Checklist:

• I have updated website/src/pages/changelog.mdx with details of this PR
• My code follows the general coding style of this project
• I have performed a self-review of my own code
• I have commented my code, particularly in hard-to-understand areas
• I have made corresponding changes to the documentation
• My changes generate no new warnings
• I have added tests that prove my fix is effective or that my feature works
• New and existing unit tests pass locally with my changes

Summary by CodeRabbit

• New Features

  • Added support for Universal Links and web URL continuation on macOS so the app can open directly from supported web links.

• Refactor

  • Unified and simplified macOS URL handling and Apple Event processing for greater compatibility and consistency; window-reopen behavior preserved.

_{✏️ Tip: You can customize this high-level summary in your review settings.}

[coderabbitai]

Walkthrough

Renames the C-exported URL handler from HandleCustomProtocol to HandleOpenURL, adds macOS Universal Link support via application:continueUserActivity:restorationHandler:, updates Apple Event URL handling to call the new entry, and removes an obsolete secure restorable state declaration. Also adjusts a reopen method signature.

Changes

Cohort / File(s)	Summary
Go export rename v3/pkg/application/application_darwin.go	Exported C bridge renamed: HandleCustomProtocol(urlCString *C.char) → HandleOpenURL(urlCString *C.char) (behavior unchanged).
Objective‑C header updates v3/pkg/application/application_darwin_delegate.h	Replaced extern void HandleCustomProtocol(char*); with extern void HandleOpenURL(char*);, removed - (BOOL)applicationSupportsSecureRestorableState:(NSApplication *)app;, added + (void)handleGetURLEvent:withReplyEvent: and updated comment to include Universal Link support.
Delegate implementation changes v3/pkg/application/application_darwin_delegate.m	Added application:continueUserActivity:restorationHandler: to handle Universal Links (calls HandleOpenURL), updated Apple Event handler to call HandleOpenURL, and changed applicationShouldHandleReopen:hasVisibleWindows: first parameter from NSApplication * to NSNotification *.
Changelog v3/UNRELEASED_CHANGELOG.md	Added entry noting macOS Universal Link support.

Sequence Diagram(s)

sequenceDiagram
    participant Apple as Apple OS
    participant Delegate as AppDelegate
    participant Go as Go runtime

    rect rgb(240, 248, 255)
    note over Apple,Delegate: Apple Event (Custom URL Scheme)
    Apple->>Delegate: handleGetURLEvent:withReplyEvent:
    Delegate->>Go: HandleOpenURL(urlString)
    Go->>Go: Parse URL & emit ApplicationLaunchedWithUrl
    end

    rect rgb(240, 255, 240)
    note over Apple,Delegate: Universal Link (NSUserActivity)
    Apple->>Delegate: application:continueUserActivity:restorationHandler:
    Delegate->>Delegate: confirm NSUserActivityTypeBrowsingWeb & webpageURL
    Delegate->>Go: HandleOpenURL(webpageURL)
    Go->>Go: Parse URL & emit ApplicationLaunchedWithUrl
    end

Loading

Estimated code review effort

🎯 3 (Moderate) | ⏱️ ~20 minutes

• Verify all bridged symbols and export comments match across Go/header/ObjC.
• Confirm Universal Link handling correctly extracts webpageURL and handles nil/error cases.
• Check callers for the changed applicationShouldHandleReopen: signature and remove stale references to the removed method.

Suggested labels

Enhancement, size:M

Suggested reviewers

• leaanthony

Poem

🐰 I hopped through Darwin's apple tree,
A URL trail led back to me,
From custom scheme to web's bright door,
One handler now receives them all—hooray! 🥕

Pre-merge checks and finishing touches

✅ Passed checks (3 passed)

Check name	Status	Explanation
Title check	✅ Passed	The title '[V3] Add universal link support for macOS' clearly and concisely summarizes the primary change—adding universal link support to the V3 macOS implementation.
Description check	✅ Passed	The description covers the main information but has gaps: missing issue reference (template requests 'Fixes #'), missing changelog update (checklist not marked), and no documentation changes noted despite template expecting them.
Docstring Coverage	✅ Passed	Docstring coverage is 100.00% which is sufficient. The required threshold is 80.00%.

✨ Finishing touches

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Post copyable unit tests in a comment

---

📜 Recent review details

Configuration used: Path: .coderabbit.yaml

Review profile: CHILL

Plan: Pro

📥 Commits

Reviewing files that changed from the base of the PR and between 31110f0 and 681d953.

📒 Files selected for processing (1)

• v3/UNRELEASED_CHANGELOG.md (1 hunks)

✅ Files skipped from review due to trivial changes (1)

• v3/UNRELEASED_CHANGELOG.md

⏰ Context from checks skipped due to timeout of 90000ms. You can increase the timeout in your CodeRabbit configuration to a maximum of 15 minutes (900000ms). (4)

• GitHub Check: Run Go Tests v3 (windows-latest, 1.24)
• GitHub Check: Run Go Tests v3 (macos-latest, 1.24)
• GitHub Check: Run Go Tests v3 (ubuntu-latest, 1.24)
• GitHub Check: semgrep-cloud-platform/scan

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands and usage tips.}

[leaanthony]

Thanks 🙏 Please could you add an entry to the changelog located at v3/UNRELEASED_CHANGELOG.md? Thanks!

[APshenkin]

@leaanthony added

[sonarqubecloud]

Quality Gate passed

Issues
0 New issues
0 Accepted issues

Measures
0 Security Hotspots
0.0% Coverage on New Code
0.0% Duplication on New Code

See analysis details on SonarQube Cloud

[leaanthony]

Would it be possible to have some short documentation on how to use this feature? I'm ok having that in a later PR if we make a ticket for it 👍 Will be updating the docs significantly over the weekend so I'm ok to delay it 👍