[V3] Add universal link support for macOS (#4712)

* Rename `HandleCustomProtocol` to `HandleOpenURL` and add universal link support on macOS.

* Update changelog.

* add docs

* add docs

---------

Co-authored-by: Lea Anthony <lea.anthony@gmail.com>

docs/src/content/docs/guides/custom-protocol-association.mdx

@@ -109,7 +109,37 @@ While Wails aims for a unified event, the underlying mechanism for custom protoc
         <!-- ... other protocols ... -->
     </array>
     ```
--   **How it Works:** When a URL like `myapp://` is opened, macOS uses LaunchServices to find the application registered for that scheme and sends it an Apple Event (`kAEGetURL`). Wails intercepts this event and translates it into the common `events.Common.ApplicationLaunchedWithUrl` Wails event, providing the URL via `e.Context().URL()`. 
+-   **How it Works:** When a URL like `myapp://` is opened, macOS uses LaunchServices to find the application registered for that scheme and sends it an Apple Event (`kAEGetURL`). Wails intercepts this event and translates it into the common `events.Common.ApplicationLaunchedWithUrl` Wails event, providing the URL via `e.Context().URL()`.
+
+#### Universal Links
+
+In addition to custom protocol schemes, macOS also supports **Universal Links**, which allow your app to be launched by regular HTTPS links (e.g., `https://myawesomeapp.com/path`). Universal Links provide a seamless user experience between your web and desktop app.
+
+<Aside type="caution">
+Universal Links require your macOS app to be **code-signed** with a valid Apple Developer certificate and provisioning profile. Unsigned or ad-hoc signed builds will not be able to open Universal Links. Ensure your app is properly signed before testing.
+</Aside>
+
+To enable Universal Links, follow the [Apple guide on supporting Universal Links in your app](https://developer.apple.com/documentation/xcode/supporting-universal-links-in-your-app). You'll need to:
+
+1. **Add entitlements** in your `entitlements.plist`:
+   ```xml title="entitlements.plist"
+   <key>com.apple.developer.associated-domains</key>
+   <array>
+     <string>applinks:myawesomeapp.com</string>
+   </array>
+   ```
+
+2. **Add NSUserActivityTypes to Info.plist**:
+   ```xml title="Info.plist"
+   <key>NSUserActivityTypes</key>
+   <array>
+     <string>NSUserActivityTypeBrowsingWeb</string>
+   </array>
+   ```
+
+3. **Configure `apple-app-site-association` on your website:** Host an `apple-app-site-association` file at `https://myawesomeapp.com/.well-known/apple-app-site-association`.
+
+When a Universal Link triggers your app, you'll receive the same `events.Common.ApplicationLaunchedWithUrl` event, making the handling code identical to custom protocol schemes.
 
 ### Windows
 
@@ -131,6 +161,25 @@ While Wails aims for a unified event, the underlying mechanism for custom protoc
 For Windows, custom protocol schemes are typically only registered when your application is installed via an installer (like the one generated by Wails with NSIS). Running the bare executable might not have the schemes registered system-wide.
 </Aside>
 
+#### Universal Links (Web-to-App Linking)
+
+Windows supports **Web-to-App linking**, which works similarly to Universal Links on macOS. When deploying your application as an MSIX package, you can enable HTTPS links to launch your app directly.
+
+To enable Web-to-App linking, follow the [Microsoft guide on web-to-app linking](https://learn.microsoft.com/en-us/windows/apps/develop/launch/web-to-app-linking). You'll need to:
+
+1. **Add App URI Handler in your MSIX manifest**:
+   ```xml title="AppPackage.appxmanifest (excerpt)"
+   <uap3:Extension Category="windows.appUriHandler">
+     <uap3:AppUriHandler>
+       <uap3:Host Name="myawesomeapp.com"/>
+     </uap3:AppUriHandler>
+   </uap3:Extension>
+   ```
+
+2. **Configure `windows-app-web-link` on your website:** Host a `windows-app-web-link` file at `https://my.app.org/.well-known/windows-app-web-link`. This file should contain your app's package information and the paths it handles.
+
+When a Web-to-App link launches your application, you'll receive the same `events.Common.ApplicationLaunchedWithUrl` event as with custom protocol schemes.
+
 ### Linux
 
 -   **Setup:** On Linux, custom protocol handling is typically managed via `.desktop` files and the MIME type system.

v3/UNRELEASED_CHANGELOG.md

@@ -17,6 +17,7 @@ After processing, the content will be moved to the main changelog and this file
 
 ## Added
 <!-- New features, capabilities, or enhancements -->
+Add universal link support for macOS by @APshenkin in [PR](https://github.com/wailsapp/wails/pull/4712)
 Refactor binding transport layer by @APshenkin in [PR](https://github.com/wailsapp/wails/pull/4702)
 
 ## Changed

v3/pkg/application/application_darwin.go

@@ -454,8 +454,8 @@ func HandleOpenFile(filePath *C.char) {
 	}
 }
 
-//export HandleCustomProtocol
-func HandleCustomProtocol(urlCString *C.char) {
+//export HandleOpenURL
+func HandleOpenURL(urlCString *C.char) {
 	urlString := C.GoString(urlCString)
 	eventContext := newApplicationEventContext()
 	eventContext.setURL(urlString)

v3/pkg/application/application_darwin_delegate.h

@@ -13,8 +13,8 @@
 
 extern void HandleOpenFile(char *);
 
-// Declarations for Apple Event based custom URL handling
-extern void HandleCustomProtocol(char*);
+// Declarations for Apple Event based custom URL handling and universal link
+extern void HandleOpenURL(char*);
 
 @interface CustomProtocolSchemeHandler : NSObject
 + (void)handleGetURLEvent:(NSAppleEventDescriptor *)event withReplyEvent:(NSAppleEventDescriptor *)replyEvent;

v3/pkg/application/application_darwin_delegate.m

@@ -17,6 +17,16 @@ extern void handleSecondInstanceData(char * message);
     HandleOpenFile((char*)utf8FileName);
     return YES;
  }
+- (BOOL)application:(NSApplication *)application continueUserActivity:(NSUserActivity *)userActivity restorationHandler:(void (^)(NSArray<id<NSUserActivityRestoring>> * _Nullable))restorationHandler {
+    if ([userActivity.activityType isEqualToString:NSUserActivityTypeBrowsingWeb]) {
+        NSURL *url = userActivity.webpageURL;
+        if (url) {
+            HandleOpenURL((char*)[[url absoluteString] UTF8String]);
+            return YES;
+        }
+    }
+    return NO;
+}
 // Create the applicationShouldTerminateAfterLastWindowClosed: method
 - (BOOL)applicationShouldTerminateAfterLastWindowClosed:(NSApplication *)theApplication
 {
@@ -46,7 +56,7 @@ extern void handleSecondInstanceData(char * message);
     if( hasListeners(EventApplicationShouldHandleReopen) ) {
         processApplicationEvent(EventApplicationShouldHandleReopen, @{@"hasVisibleWindows": @(flag)});
     }
-    
+
     return TRUE;
 }
 - (void)handleSecondInstanceNotification:(NSNotification *)note;
@@ -185,7 +195,7 @@ extern void handleSecondInstanceData(char * message);
 + (void)handleGetURLEvent:(NSAppleEventDescriptor *)event withReplyEvent:(NSAppleEventDescriptor *)replyEvent {
    NSString *urlStr = [[event paramDescriptorForKeyword:keyDirectObject] stringValue];
    if (urlStr) {
-       HandleCustomProtocol((char*)[urlStr UTF8String]);
+       HandleOpenURL((char*)[urlStr UTF8String]);
    }
 }
 @end