H5中使用通用链接universallink跳转iOS App的坑

一、背景

移动端H5开发中，经常有需要点击某个按钮直接跳转打开app的需求。比如：我们有一个邀请注册的页面，从app分享到微信，用户在微信内浏览页面，点击页面中的“打开app”按钮引导跳转浏览器（微信内限制了直接跳转APP，故需要先引导到浏览器，若需微信内直接跳转，参考：微信官方文档，需要满足一些特定条件才可以），在浏览器中再点击“打开app”跳转app，传统的scheme跳转打开APP会有一个“在xxapp中打开”的二次确认弹窗，且当APP未安装时点击会提示“浏览器打不开该网页，因为网址无效”，体验比较差。故需要使用通用链接跳转，但是通用链接跳转也有很多需要注意的坑，为防止后续再走弯路，这里将通用链接配置和使用流程做个完整的记录。

二、通用链接的配置

参考苹果官方文档

• 将关联的域名文件添加到您的网站。
  在你的网站域名根目录或 /.well-known 目录下，上传一个名为 apple-app-site-association（无后缀名）的JSON文件 。该文件用于声明你的网站允许哪些对应的 App 打开哪些路径的链接。json文件内容参考如下配置：

{
    "applinks": {
        "details": [
            {
                "appIDs": [ "ABCDE12345.com.example.app" ],//你的Team ID + Bundle ID
                "components": [
                		{
                        "/": "/app/*",// 匹配/app/下的所有页面
                        "comment": "普通app页面都打开App"
                    },
                    {
                        "/": "/product/*",        // 匹配路径 /product/ 下的所有页面
                        "#": "share",             // 且 fragment 是 share（即#号后面的内容）
                        "?": { "albumname": "iPhone" }, // 且查询参数 albumname=iPhone
                        "comment": "只有当所有条件都满足时才匹配"
                    },
                    {
                        "/": "/checkout/success", // 匹配路径 /checkout/success
                        "#": "no_universal_links",// 但如果 fragment 是 no_universal_links
                        "exclude": true,          // 则排除（不打开 App）
                        "comment": "支付成功页有时需要显示网页内容"
                    },
                    
                ]
            }
        ]
    }
}

• 将关联的域权限添加到您的应用。
  在XCode - Target - Signing & Capabilities - Associated Domains中添加域名。如图：
  

三、通用链接的使用

1. app中添加代码以响应通用链接
   假设链接是https://www.example.com/product/#share?albumname=iPhone,则如下代码会在打开app后输出album = iPhone

func application(_ application: UIApplication,
                 continue userActivity: NSUserActivity,
                 restorationHandler: @escaping ([UIUserActivityRestoring]?) -> Void) -> Bool
{
    // Get URL components from the incoming user activity.
    guard userActivity.activityType == NSUserActivityTypeBrowsingWeb,
        let incomingURL = userActivity.webpageURL,
        let components = NSURLComponents(url: incomingURL, resolvingAgainstBaseURL: true) else {
        return false
    }
    // Check for specific URL components that you need.
    guard let path = components.path,
    let params = components.queryItems else {
        return false
    }    
    print("path = \(path)")

    if let albumName = params.first(where: { $0.name == "albumname" } )?.value{
        print("album = \(albumName)")
        return true
    } else {
        print("Either album name or photo index missing")
        return false
    }
}

2. h5页面使用通用链接跳转

   • 浏览器直接输入通用链接
     按前面的配置。现在在浏览器直接输入https://www.example.com/app/123，在有安装app的情况下，就会在页面顶部提示，在“xxx”app中打开，点击打开即可跳转app。若没有安装，就单纯显示页面内容，没有提示。

   • 微信内引导跳转浏览器打开
     比较正常场景应该是从微信内引导跳转浏览器，如果通用链接生效并安装了app，则跳转浏览器后就会接着跳转app。如果想要跳转浏览器后点击“打开xxapp”按钮再跳转App，则页面路径和通用链接应使用不同域名，比如：页面路径是https://www.example.com/app/123，通用链接路径是https://www.universal.com/app/123。如果使用相同域名，浏览器会认为用户想要跳转页面而不是打开app，因此只会在浏览器中打开该链接。 注意，域名修改后XCode的Associated Domains配置也要相应修改成，applinks:www.universal.com，如图：
     

   • 隐藏的坑。

     1. 如果用户修改了apple-app-site-association文件，必须重装app，否则修改的通用链接不会生效。因为iOS是在首次安装时拉取apple-app-site-association文件。如果卸载重装也不生效，可能是苹果的CDN缓存问题，测试时可将XCode配置改成applinks:www.universal.com?mode=developer，添加developer限制，跳过苹果的CDN缓存，这样的话测试的设备必须开启开发者模式，且启用 “设置”>“开发者”中的“关联域名开发” 选项。测试通过后再将配置还原成，applinks:www.universal.com，苹果的CDN缓存一般会在48小时后更新。
     2. 必须是真实用户点击。以下情况 一定不生效：JS 自动触发（setTimeout / onload）、页面一加载就调用。非点击事件（滚动、接口回调），必须用a标签，click事件herf跳转，且最好不要是异步操作。
     3. 如果用户之前有过以下几种操作：

     • 之前点击的时候app没装

     • App 装了但没及时响应

     • 用户点过 “在 Safari 中打开”

     • 之前用 scheme / JS 跳转失败过

       iOS 会记住这个决定，之后的行为就是：永远不再唤起 App，无论是 a标签，herf、跨域、Safari 地址栏，都会只打开网页。如果要恢复跳转，需要在浏览器或备忘录中输入这个地址，长按，选择“在xxapp中打开”，即可重置iOS的记忆。这也是建议通用链接不要和页面链接用同一个域名的原因之一，因为页面链接很容易触发这些行为，一旦用户触发，通用链接将永远无法在生效，用户不会和开发者一样知道如何重置，开发者维护和排查也比较困难。

   • 进一步优化
     如果需要对已安装app的用户，直接跳转app并在app打开目标H5，对于未安装app的用户，跳转下载页引导去appstore下载。则通用链接直接配置成子域名下的app下载页即可，目标H5路径可通过约定参数获取。如：通用链接为https://www.universal.com/h5/#/appdownload?destUrl=h5/#/share（destUrl指定打开app后需要跳转的页面路径），apple-app-site-association配置参考如下：

{
    "applinks": {
        "details": [
            {
            	"appIDs": [ "AB6B78BFS6E.com.xmyf.escort" ],
            	"components": [
		    		 {
		    		 	"/": "/h5/*",
		    		 	"#": "/appdownload",
		    		 	"comment": "匹配路径/h5/下的所有页面,且fragment是/appdownload（即#号后面的内容）,对应app下载页https://www.universal.com/h5/#/appdownload"
                    }
                ]
            }
        ]
    }
}