ios Universal Link 配置教程 + 踩坑记录

Univeral Link的配置有3方面：Apple Developer网站配置、XCode配置、服务器资源配置（apple-app-site-association文件创建和存放）

首先说下我们的需求：支持一个域名下多个APP（目前是两个）的universal Link 跳转

Universal Link访问地址为：

（1）steel项目：https://chat.vol.com/steel/

  (2) companychat项目： https://chat.vol.com/companychat/

一、Apple Developer网站配置

项目的App ID 需要开通Associated Domains。

【操作】：（1）登录Apple Developer网站 （Sign In - Apple），点开Identifiers一栏，找到我们项目的App ID。点击这个APP ID，进入APP ID设置页面。  

 （2）在APP ID的设置页面，勾选Associated Domains。（如果在创建配置文件Profiles之后再勾选的Associated Domains，需要重新创建一下配置文件Profiles，然后下载最新的改APP ID的配置文件Profiles，重新安装上配置文件Profiles）。

二、服务器资源配置（apple-app-site-association文件创建和存放）

【原理】：在第一次安装APP的时候，手机的iOS系统会去指定的路径（这个路径是后面后端开发人员给的）下载apple-app-site-association文件。通过这个文件，iOS系统就会知道哪些URL是Universal Links，哪些不是Universal Links。从而我们指定的路径可以发生跳转。这个apple-app-site-association文件需要开发者去创建和放到一个苹果可以访问的服务器上。这个过程在XCode调试的时候也会发生。

1、apple-app-site-association文件创建

新建一个名字为apple-app-site-association的纯文本文件（Json格式），不要有任何后缀，文件内容为

{
    "applinks": {
        "apps": [],
        "details": [
            {
                "appID": "团队ID.软件BundleID/APP ID",
                "paths": ["限制的路径节点名，没有限制就填*"]
            }
        ]
    }
}

上述填写内容，主要是appID和paths的填写，其他不用理会。

一组{"appID":"XXX",  "paths":"[xxx]"}对应一个APP。有多少个APP，就写多少组。我们的需求是一个域名下支持有两个APP使用Universal Link。所以我这里写了两组。

（1）填写appID

appID最正确的填写方式，就是XCode运行后，找到这个包，然后找到这个包下的配置文件embedded.mobileprovision, 在这个文件中的application-identifier是什么，APP ID就填写什么。

【找appID方法】：参考下我的这篇文章Universal Link的apple-app-site-association填写appID最正确的方法_jifaliwo123的博客-CSDN博客

（2）填写paths

如果是一个服务器对应一个APP跳转，那么这里其实填写一个 “*”就可以了。如果一个服务器支持多个APP跳转，则需要用不同的专用路径节点（填写“/节点/*”）去互相屏蔽。比如地址https://chat.vol.com/AHost/XXX（paths填写"/AHost/*"） 只能用于A应用的跳转；地址https://chat.vol.com/BHost/XXX（paths填写"/BHost/*"）只能用于B应用的跳转。

举个例子，因为我们需求是支持一个域名下多个APP（目前是两个）的universal Link 跳转

Universal Link访问地址为：

（1）steel项目：https://chat.vol.com/steel/

  (2) companychat项目： https://chat.vol.com/companychat/

所以，下面是我用的文件（大概就这样）这两个APP都是在同一个开发者账号下，所以从embedded.mobileprovision, 在这个文件中的application-identifier拷贝到的appID里面的team ID都是同一个

{
    "applinks": {
        "apps": [],
        "details": [
            {
                "appID": "CIKJHYGBHT.com.volcano.VOLSteelChat",
                "paths": ["/steel/*"]
            },
            {
                "appID": "CIKJHYGBHT.com.volcano.VOLCompanyChat",
                "paths": ["/companychat/*"]
            }
        ]
    }
}

2、apple-app-site-association文件的存放

这个文件创建好之后，交给后端人员。让他们把这个文件放到指定的url的根目录下（URL不一定要指定，可以后端人员给啥我们就用啥也行。这个URL在配置XCode会用到）。这个根目录下除了放这个文件不要放其他东西。我们的URL是https://chat.vol.com/。

【验证】：验证后端是否正确放置的方法，这是浏览器输入这个地址，会直接下载apple-app-site-association文件。如果没有下载到这个软件，说明服务器配置不对。

【注意1】：我这里下载下来的apple-app-site-association文件名字不是“apple-app-site-association”，但是这没有影响。只要放到服务器的名字是apple-app-site-association就行。

 

【注意2】：对于paths有填写专用路径节点的情况（比如我这里写的【"paths": ["/companychat/*"]】）， 服务器不用在这个路径下添加真实的文件访问路径！访问applinks这个域名网址的时候，找不到的话不要重定向！！访问applinks网址的时候，找不到的话不要写一个专门的空白页！

  

三、XCode配置

XCode 的配置下图都统一给出来了。下面逐步说一下。

1、点击Signing & Capabilities一栏

2、一定要点击这个All。因为这里的一些配置会区分Debug 版和Release版。粗心一点的，就会在后面混淆了是Debug 还是Release。

3、（1）一定要取消掉这个Automatically manage siging（自动签名）的勾选（取消勾选）。要使用手动签名的方式。否则，iOS系统在APP启动的时候有可能不会去我们配置的applinks地址去下载apple-app-site-association 文件。

（2）因为我们使用的手动签名，所以在这里要选择到能用的Proivsioning Profile。选择了之后运行看是否报错。报错的话再去重新去 Apple Developer网站 （Sign In - Apple）生成一个正确的下载下来装上。

4、配置Associated Domains的applinks，格式为：“applinks:xxx”。这里的xxx为一个域名，没有“https://”前缀，也没有“/”后缀。

在第二步服务器资源配置（apple-app-site-association文件创建和存放）的2、apple-app-site-association文件的存放的步骤里，我们已经拿到了一个URL。将这个URL填入。

我们的服务器地址为【https://chat.vol.com/】，所以这里填写的是：【applinks:chat.vol.com】

这里有一个要注意的地方：

一般来说，新配置了applinks:的话，工程主目录会出现一个APPNAME.entitlements文件，里面有我们刚配置的applinks。设置完applinks后我们需要去检查一下，这个文件有没有存在。如果设置了applinks:但是Xcode上没有这个文件的话，前往Finder目录下看看有没有（一般来说都会即时生成一个在文件目录下）。

【非常的极端情况】：如果XCode和Finder下都没有，那就试试手动创建一个——新建里没看到这个文件类型，试试拷贝别人的.entitlements文件改改看能不能用，最后填写一下applinks。===>这个方法没遇到过没试过= 。=

四、检验的时候到了

上面的步骤都做完，检查完之后。正常来说，universal link就是配置好了可以测试使用了。

测试方法：

1、在通讯录输入完整地址： https://+applinks配置的域名+apple-app-site-association里的paths

在通讯录点击这个地址，看是否能发生跳转，跳转到手机已经安装上的APP

2、在1、中的地址拷贝。在浏览器输入并前往，页面会出现一个下载该APP的区域。（也有可能会出现一个error页面，但是往下滑动一下页面，那个下载APP的区域就出来了）

五、遇到的坑 

遇到的问题大部分都是apple-app-site-association相关的问题。

 1、当检测的时候，Universal link没有跳转。解决的思路是：

（1）iOS系统有没有做apple-app-site-association的请求。使用抓包软件去抓包看一下是否有请求apple-app-site-association 的URL

（2）iOS系统请求到的apple-app-site-association文件是长什么样子的（有可能我们的apple-app-site-association有隐藏的特殊字符什么的）。这个也是通过使用抓包软件查看response。

（3）iOS系统能正确下载apple-app-site-association文件，但是依然没有跳转，那就有可能是apple-app-site-association的填写的appid不对。

【（1）（2）思路解决】：通过抓包软件查看apple-app-site-association的请求。

使用抓包软件，抓包手机的网络请求。

• 先卸载测试机/模拟器上的APP，
• 打开抓包软件开始抓包，然后运行APP到手机上。
• 如果没有找到applinks的请求，说明XCode配置有问题。导致iOS系统直接认为这个APP没有配置Universal Links，不需要去访问applinks
• 如果在抓包软件上能找到applinks请求，查看请求到的数据里面有没有这个apple-app-site-association文件，或者apple-app-site-association里的内容是否为纯JSON的内容，Json内容是否写对了或者是否有缺失等。

我用的是charles抓包。运行在iPhone手机上。

2、不用过于纠结apple平台的检测apple-app-site-association 网站（https://search.developer.apple.com/appsearch-validation-tool/）的结果（Error no apps associated with url），这个结果没有多大的指导性意义。这个网站其实主要就是去访问我们的applinks地址，看是否有下载到apple-app-site-association文件。我们更应该关注的是（1）iOS系统有没有做apple-app-site-association的请求 （2）iOS系统请求到的apple-app-site-association文件是长什么样子的（有可能我们的apple-app-site-association有隐藏的特殊字符什么的）

我的那个URL这个网站的结果是

3、因为XCode的签名用的自动签名（即勾选了Automatically manage siging），导致iOS 系统 直接没有在APP 安装的时候去请求apple-app-site-association文件。

【解决】：取消勾选Automatically manage siging

4、apple-app-site-association的填写appID 填写问题。

因为我们的开发者账号有多个人，Proivsioning Profile 的签名ID和bundle ID所属的Team ID是不一样的。我把Proivsioning Profile 的签名ID写在了appID里（因为看到有教程说应该使用其工程里的Proivsioning Profile的签名ID）。

【解决】：不用纠结这个bundle ID所属的Team ID跟Proivsioning Profile的签名ID是否一致。直接去XCode编译后的包里，找到embedded.mobileprovision 文件，该文件里 application-identifier显示的内容就是apple-app-site-association 里的appID要填写的内容。

embedded.mobileprovision获取教程：Universal Link的apple-app-site-association填写appID最正确的方法_jifaliwo123的博客-CSDN博客 

5、 对于paths有填写专用路径节点的情况（比如我这里写的【"paths": ["/companychat/*"]】）， 服务器不用在这个路径下添加真实的文件访问路径！访问applinks这个域名网址的时候，找不到的话不要重定向！！访问applinks网址的时候，找不到的话不要写一个专门的空白页！

  

6、你的浏览器清理缓存后再访问 apple-app-site-association文件 的地址。我遇到的情况是：apple-app-site-association文件改动后重新放到服务器。但是我电脑浏览器下载下来的 apple-app-site-association文件依旧是修改前的数据。浏览器清理缓存后，下载下来的最新的apple-app-site-association文件。

7、Charles安装和配置HTTPS证书

苹果要求的applinks 支持https。而Charles需要做一些配置才能抓取到https 请求的数据包。否则获取到的包是乱码unknown 包。Charles安装和配置HTTPS证书我按照的这个文章的来配置的：

掘金

不过我在里面的【2.1.SSL Proxying Settings 】这个步骤没做对，导致配置完还是抓取不到unknown 包。

【错误配置】：2.1步骤中host填写的【 *.443 】 

【正确配置】：按照圈出来的地方填写就可以

六、参考文档

配置Universal Links需要注意的点

iOS Universal Link通用链接（多个app）+配置微信 - 简书

Xcode编译后的文件路径_zhuimengfuyun的专栏-CSDN博客_xcode 编译好的文件在哪https://juejin.cn/post/6844904097133363214Xcode编译后的文件路径_zhuimengfuyun的专栏-CSDN博客_xcode 编译好的文件在哪

iOS Universal Links踩坑之旅 - 简书

Universal Link踩坑后的一些总结 - 简书

iOS微信授权登录与通用链接配置 | 拿根针尖对麦芒