iOS应用中prefersEphemeralWebBrowserSession设为false时Universal Links失效问题

核心原因 #

当prefersEphemeralWebBrowserSession设为false时，ASWebAuthenticationSession使用Safari的共享会话，但它对Universal Links的触发有严格限制：

• 会话只会识别与自身初始化时指定的回调机制绑定的URL，包括你设置的callbackURLScheme，或者明确关联到当前App且被会话认定为合法回调路径的Universal Links。
• 直接使用第三方（比如Notion）的默认Universal Links时，会话可能不会触发跳转，因为它默认只允许回调到与当前会话关联的目标，而非任意第三方Universal Links。

解决步骤 #

1. 确认Universal Links基础配置正确

   • 在Xcode项目的Signing & Capabilities中添加Associated Domains，确保包含applinks:你的回调域名。
   • 服务器根目录或.well-known目录下的apple-app-site-association文件必须正确配置，包含你的Team ID、Bundle ID，以及回调路径的映射规则。

2. 调整Notion回调URL为自定义Universal Links

   • 在Notion开发者后台，将授权回调URL设置为你自己域名下的Universal Links路径（比如https://yourdomain.com/notion-callback）。
   • 确保该路径在apple-app-site-association中被配置为跳转至你的App。

3. 正确处理App内的Universal Links回调

   • 在AppDelegate或SceneDelegate中实现Universal Links的处理方法：

     // AppDelegate
     func application(_ application: UIApplication, continue userActivity: NSUserActivity, restorationHandler: @escaping ([UIUserActivityRestoring]?) -> Void) -> Bool {
         if userActivity.activityType == NSUserActivityTypeBrowsingWeb, let url = userActivity.webpageURL {
             // 将URL传递给ASWebAuthenticationSession的处理逻辑
             if let session = yourAuthenticationSession {
                 session.cancel()
                 // 解析URL中的授权码，完成Notion登录流程
                 handleNotionCallback(url: url)
             }
             return true
         }
         return false
     }
     
     // SceneDelegate
     func scene(_ scene: UIScene, continue userActivity: NSUserActivity) {
         if userActivity.activityType == NSUserActivityTypeBrowsingWeb, let url = userActivity.webpageURL {
             if let session = yourAuthenticationSession {
                 session.cancel()
                 handleNotionCallback(url: url)
             }
         }
     }
     

4. 确保ASWebAuthenticationSession初始化参数正确

   • 初始化时指定callbackURLScheme（即使使用Universal Links，这个参数也有助于会话识别合法回调），并确保completionHandler能处理回调逻辑：

     let session = ASWebAuthenticationSession(url: notionAuthURL, callbackURLScheme: "yourappscheme") { url, error in
         if let url = url {
             handleNotionCallback(url: url)
         }
     }
     session.prefersEphemeralWebBrowserSession = false
     session.start()
     

5. 排查iOS版本适配问题

   • iOS 13及以上版本优先使用SceneDelegate处理Universal Links，确保相关逻辑在SceneDelegate中也有实现；iOS 12及以下则依赖AppDelegate。

内容的提问来源于stack exchange，提问作者kdrtibor