Appy

深度链接

什么是 Associated Domains?

一句话解释

Associated Domains(关联域名)是 Apple 的一项能力和权限(entitlement),列出与 App 关联的网站域名。每一条由服务和域名组成,比如 applinks:example.com。配合该域名下的 apple-app-site-association 文件,它可以启用通用链接、共享网站凭据、接力(Handoff)和 App Clip。

权限里写什么

这项权限是一组 service:domain 格式的字符串。Apple 定义了四种服务:applinks 用于通用链接;webcredentials 让 App 使用为网站保存的密码;activitycontinuation 用于接力;appclips 把 App Clip 和域名绑定起来。

域名只写裸域名:不带 https://,不带路径,结尾没有斜杠,按 Apple 技术说明的要求也不带端口号。每个子域名单独写一条。除 appclips 以外的服务,都可以用 *. 前缀匹配所有子域名,比如 applinks:*.example.com。

它怎样和域名下的文件配合

这项权限是双向校验的一半。App 声明某个域名,域名在自己的 apple-app-site-association(AASA)文件里列出 App 的 ID 来确认这份声明。任何一半缺失,对应的服务就不会启用,iOS 也不会向用户提示什么。

App 安装时,系统会为列出的每个域名下载这个文件。从 iOS 14 起,这个请求发给 Apple 管理的 CDN,而不是你的服务器。Apple 的文档说,CDN 会在 24 小时内请求文件,设备大约每周检查一次更新。

配置和测试

在 Xcode 里打开 target 的 Signing & Capabilities 标签页,添加 Associated Domains 能力,每个域名填一行。这一步同时会为 App ID 打开这项功能。App Clip 需要在 App target 和 App Clip target 上各写一条相同的条目。

如果服务器从公网访问不到,在条目后面加上 ?mode=developer。处于开发者模式的设备会直接去取文件,而且只有用开发描述文件签名的包才能用这个模式。还有一种 managed 模式,面向纳入移动设备管理的设备。发布前要把后缀去掉:正式包应该和所有人的手机一样走 CDN。Apple 的技术说明还介绍了一个在设备上快速检查的办法:在“开发者”设置里打开 Associated Domains Development 后,Diagnostics 页面会告诉你某个地址对已安装的 App 是否有效。

示例权限条目
applinks:example.com, webcredentials:example.com

在这里试试

为你的 App 生成文件

填入 Team ID 和 bundle ID,或包名和签名指纹,即可得到可直接放到服务器上的 apple-app-site-association 或 assetlinks.json 文件。

应用

添加所有需要打开这个域名链接的应用。每个应用都会成为 appIDs 中的一项。

  1. 应用 1

    10 位字符,在 Apple Developer 账号的 Membership details 中。

    在 Xcode 的应用 target 中查看,例如 com.example.app。

会打开应用的路径

规则从上到下依次匹配,先匹配到的规则生效,所以排除规则要放在范围更大的规则之前。* 匹配任意数量的字符,? 只匹配一个字符。

  1. 规则 1

    用 & 连接的 name=value 对

其他服务

你的文件

apple-app-site-association

示例。填写你的信息后会被替换。

{
  "applinks": {
    "details": [
      {
        "appIDs": [
          "ABCDE12345.com.example.app"
        ],
        "components": [
          {
            "/": "/*"
          }
        ]
      }
    ]
  }
}

在你的浏览器中生成,不会发送到任何地方。

放在哪里

文件托管位置

  1. 上传到 https://你的域名/.well-known/apple-app-site-association,不要加 .json 扩展名。
  2. 通过 HTTPS 提供,证书有效,直接返回 200,不要重定向。
  3. 返回 Content-Type: application/json 响应头。
  4. 链接中用到的每个主机都要配置:example.com 和 www.example.com 是两个主机,各自需要文件和 applinks: 条目。
  5. Apple CDN 会在 24 小时内抓取新文件。在此期间可以用 ?mode=developer 测试。
用验证工具检查域名

不想自己托管文件?智能链接免费使用;在 Enterprise 套餐中,Appy 会在应用的专属链接域名上提供这两个文件。

免费创建链接
延伸阅读iOS 和 Android 通用链接完整指南在通用链接和 App Links 的完整配置里,Associated Domains 条目处在哪一步,逐步说明。

常见问题

Associated Domains 和通用链接有什么区别?

Associated Domains 是机制,通用链接是建立在它之上的一项功能。这项权限还能启用共享网站凭据、接力和 App Clip。具体到通用链接,你要添加一条 applinks: 条目,并在域名文件的 applinks 部分列出 App。

Associated Domains 里可以用通配符吗?

可以。在域名前加 *. 就能匹配它的所有子域名,比如 applinks:*.example.com,文件放在根域名上。appclips 服务不允许用通配符,而且通配符不包含根域名本身,根域名要单独写一条。

为什么我的 Associated Domains 条目不生效?

先查三个最常见的原因。条目里带了 scheme、路径或端口。条目里的域名和提供文件的主机不一致,比如一个是 example.com,一个是 www.example.com。或者文件有重定向、被拦截,Apple 的 CDN 始终拿不到副本。

  • 通用链接(Universal Links)

    通用链接(Universal Links)是 Apple 从 iOS 9 起支持的 https 链接,能直接打开已安装的 iOS App,而不是网站。它需要 App 里的 Associated Domains 权限(比如 applinks:example.com),以及域名下的 apple-app-site-association 文件。没装 App 时,同一条链接打开的就是网站。

  • apple-app-site-association(AASA)文件

    apple-app-site-association(AASA)是放在域名 /.well-known/ 目录下的 JSON 文件,用来证明这个域名和你的 App 是关联的。文件里列出 App ID(Team ID 加 bundle ID)和要在 App 里打开的路径。没有它,通用链接不会生效,只会打开网站。

  • App Clip(轻 App)

    App Clip(轻 App)是 iOS App 的轻量版本,用户不用安装完整 App 就能使用。它由一次调用唤起,比如 App Clip 码、二维码、NFC 标签、“信息”里的链接或 Safari 里的横幅,完成一件明确的事,然后可以引导用户安装完整 App。

查看全部术语

一条链接,搞定 App Store、Google Play 和网站

Appy 免费版提供 4 条链接和对应的二维码:按设备自动跳转 App Store、Google Play、华为应用市场、三星 Galaxy Store 或小米 GetApps,电脑端打开网站。没有广告,不用绑卡。