Asset Links Specification 文件格式参考

 个推关于对App Links的支持

 Android App Links是一种特殊类型的deep link，它允许你的website url能够立即打开app对应的内容而且无需弹出一个选择对话框让用户去选择打开该url的app。
 添加intent filters（参考[Create Deep Links to App Content)]），然后验证你同时拥有website url和该app，最后系统会自动导航该url打开你对应的app页面。
 验证你是该app和website url的所有者，需要遵循以下步骤：

• 请求必要的app link verification ，这会通知系统去验证app是否属于当前website url。
• 在Digital Asset Links JSON file 内定义website和app的关系，并且将其放在https://domain.name/.well-known/assetlinks.json。
  你可以在以下资源内查找相关信息：
• Supporting URLs and App Indexing in Android Studio
• Creating a Statement List

The difference between deep links and app links

一个deep link是一个可以让用户直接进入app指定页面的intent filter。点击以下链接可能会打开一个选择对话框，让用户去选择能够处理当前链接的app。Figure 1表示了在用户点击了一个地图链接之后，弹出了一个对话框让用户去选择打开的应用。

Figure 1. The disambiguation dialog

  Android App Link 是一个基于已经验证的website url的deep link。只要安装了对应的app，那么在点击了特定链接可以立即打开app内对应的页面，而没有app选择框。用户也可以在系统设置里面修改打开该链接的app。

Request app links verification

  为app开启链接验证，在任何一个包含有 android.intent.action.VIEW intent action和android.intent.category.BROWSABLE intent category的web url intent filters中设置android:autoVerify="true",如下所示：

<activity ...>

    <intent-filter android:autoVerify="true">
        <action android:name="android.intent.action.VIEW" />
        <category android:name="android.intent.category.DEFAULT" />
        <category android:name="android.intent.category.BROWSABLE" />
        <data android:scheme="http" android:host="www.example.com" />
        <data android:scheme="https" />
    </intent-filter>

</activity>

 当在intent filters内设置过android:autoVerify="true"，在android6.0以及更高的系统上安装app时会让系统去验证所有的host以及相关联的web url。验证涉及以下步骤：

1. 系统会验证包含以下内容的所有的intent filters：

• Action:android.intent.action.VIEW
• Categories:android.intent.category.BROWSABLE和android.intent.category.DEFAULT
• Data scheme:http or https

2. 在以上intent filters中每一个主机名，Android会查询相应网站在https://hostname/.well-known/assetlinks.json的Digital Asset Links file。

 在manifest文件内，只有当系统为每一个主机找到对应的Digital Asset Links file，才会将app设置为对应Url 模式的默认处理器。

Supporting app linking for multiple hosts

 对于每一个域名，系统都有能力通过Digital Asset Link files去验证intent filters内的host。只要有一个验证失败了，app就不能成为对应url的默认处理app。如Create Deep Links to App Content所描述的一样，系统会有处理intent的标准行为。
 如果具有以下intent filters的app没有在https://www.example.com/.well-known/assetlinks.json或者https://www.example.net/.well-known/assetlinks.json找到assetlinks.json文件，那么链接验证将会失败：

<application>

  <activity android:name=”MainActivity”>
    <intent-filter android:autoVerify="true">
      <action android:name="android.intent.action.VIEW" />
      <category android:name="android.intent.category.DEFAULT" />
      <category android:name="android.intent.category.BROWSABLE" />
      <data android:scheme="http" android:host="www.example.com" />
      <data android:scheme="https" />
    </intent-filter>
  </activity>
  <activity android:name=”SecondActivity”>
    <intent-filter>
      <action android:name="android.intent.action.VIEW" />
      <category android:name="android.intent.category.DEFAULT" />
      <category android:name="android.intent.category.BROWSABLE" />
      <data android:scheme="https" android:host="www.example.net" />
    </intent-filter>
  </activity>

</application>

 在同一个intent filter内的<data>标签的属性会被合并组合成多种变种。在上面的第一个intent filter内有一个只指定了https scheme的<data>标签，但是它会组合其它<data>标签，所以它支持http://www.example.com和https://www.example.com。因此，如果你想要定义特定的URI scheme和domains的组合，就需要创建不同的intent filters。

Supporting app linking for multiple subdomains

The Digital Asset Links protocol把子域名独立与host。如果你的intent filter列出了不同子域名的多个主机，那么你就要为每个域名都发布一个有效的assetlinks.json。以下intent filter包含了www.example.com和mobile.example.com，所以就需要在https://www.example.com/.well-known/assetlinks.json和https://mobile.example.com/.well-known/assetlinks.json都发布一个有效的assetlinks.json。

<application>
  <activity android:name=”MainActivity”>
    <intent-filter android:autoVerify="true">
      <action android:name="android.intent.action.VIEW" />
      <category android:name="android.intent.category.DEFAULT" />
      <category android:name="android.intent.category.BROWSABLE" />
      <data android:scheme="https" android:host="www.example.com" />
      <data android:scheme="https" android:host="mobile.example.com" />
    </intent-filter>
  </activity>
</application>

 在此之外，如果你使用通配符定义了一个主机名（比如*.example.com），那么你就必须要在根域名 (example.com)发布assetlink.json，比如以下的intent filter的app会通过所有关于（example.com）的子域名的验证，比如(such as foo.example.com)，只要assetlinks.json被发布在https://example.com/.well- known/assetlinks.json。

<application>
  <activity android:name=”MainActivity”>
    <intent-filter android:autoVerify="true">
      <action android:name="android.intent.action.VIEW" />
      <category android:name="android.intent.category.DEFAULT" />
      <category android:name="android.intent.category.BROWSABLE" />
      <data android:scheme="https" android:host="*.example.com" />
    </intent-filter>
  </activity>
</application>

Declare website associations

 必须要有一份发布的Digital Asset Links JSON file去表示app和website之间的关联并且验证app的url intent。Json 文件使用以下字段去验证所关联的app：

• package_name:app内build.gradle定义的application id
• sha256_cert_fingerprints：app签名证书的SHA256 fingerprints。你可以通过java tool使用以下命令来生成fingerprint。

$ keytool -list -v -keystore my-release-key.keystore

该字段支持多类型fingerprint用来支持app的不同版本，比如调试版本和正式版本。
以下assetlinks.json文件示例授予了链接打开com.example app的权限。

[{
"relation": ["delegate_permission/common.handle_all_urls"],
"target": {
"namespace": "android_app",
"package_name": "com.example",
"sha256_cert_fingerprints":
["14:6D:E9:83:C5:73:06:50:D8:EE:B9:95:2F:34:FC:64:16:A0:83:42:E6:1D:BE:A8:8A:04:96:B2:3F:CF:44:E5"]
}
}]

Associating a website with multiple apps

 在同一份assetlinks.json文件内，可以为同一个website关联多个app。如下所示：

[{ "relation": ["delegate_permission/common.handle_all_urls"],
"target": {
"namespace": "android_app",
"package_name": "com.example.puppies.app",
"sha256_cert_fingerprints":
["14:6D:E9:83:C5:73:06:50:D8:EE:B9:95:2F:34:FC:64:16:A0:83:42:E6:1D:BE:A8:8A:04:96:B2:3F:CF:44:E5"]
}
},
{ "relation": ["delegate_permission/common.handle_all_urls"],
"target": {
"namespace": "android_app",
"package_name": "com.example.monkeys.app",
"sha256_cert_fingerprints":
["14:6D:E9:83:C5:73:06:50:D8:EE:B9:95:2F:34:FC:64:16:A0:83:42:E6:1D:BE:A8:8A:04:96:B2:3F:CF:44:E5"]
}}]

 在同一个web host下，不同的app可以处理不同的资源链接。比如，app1可能定义了处理https://example.com/articles的intent filters，app2可能定义了https://example.com/videos的intent filters。

多个关联同一个域名的app可能被一个或者多个证书签名。

Associating multiple websites with a single app

 多个类型的网站可以定义关联同一个app在它们个字的assetlinks.json，以下示例表示了如何定义example.com 和 example.net和app1的关联。第一个文件定义了example.com 和app1
的关联：
https://www.example.com/.well-known/assetlinks.json

[{
"relation": ["delegate_permission/common.handle_all_urls"],
"target": {
"namespace": "android_app",
"package_name": "com.mycompany.app1",
"sha256_cert_fingerprints":
["14:6D:E9:83:C5:73:06:50:D8:EE:B9:95:2F:34:FC:64:16:A0:83:42:E6:1D:BE:A8:8A:04:96:B2:3F:CF:44:E5"]
}
}]

下一个示例显示了example.net 和app1的关联，唯一的区别在于文件的位置。
https://www.example.net/.well-known/assetlinks.json

[{
"relation": ["delegate_permission/common.handle_all_urls"],
"target": {
"namespace": "android_app",
"package_name": "com.mycompany.app1",
"sha256_cert_fingerprints":
["14:6D:E9:83:C5:73:06:50:D8:EE:B9:95:2F:34:FC:64:16:A0:83:42:E6:1D:BE:A8:8A:04:96:B2:3F:CF:44:E5"]
}
}]

Publishing the JSON verification file

 你必须要在以下位置发布JSON验证文件：

https://domain.name/.well-known/assetlinks.json

确定以下几点：

• assetlinks.json文件需要是application/json格式。
• assetlinks.json文件要能够被https连接访问到，不需要管intent filter 的data scheme定义了HTTPS。
• assetlinks.json文件不能是通过重定向访问到（301或者是302），可以被机器所访问（你的robots.txt必须要能爬取/.well-known/assetlinks.json）。
• 如果你的app links支持多类型主机域名，你就必须要在每个域名上都配置一个assetlinks.json。具体请见Supporting app linking for multiple hosts。
• 不要在manifest文件里写入dev/test 地址，可能会导致无法在公网上访问（比如只能通过vpn访问），这种情况下的变通方案就是取配置configure build variants，为dev环境生成不同的manifest文件。

Test app links

在实现app links功能之后，你需要测试系统是否正确关联了app和web sites，按你所期望地处理url 请求。
为了测试一个存在的说明文件，你可以使用 Statement List Generator and Tester工具。

Confirm the list of hosts to verify

在测试得时候，你需要确认需要验证的host。制作一个关于包含以下属性和元素的intent filters的url列表。

• android:scheme属性值需要是https或者http。
• android:host需要是一个url 模式的域名。
• 需要有android.intent.action.VIEW元素。
• android.intent.category.BROWSABLE。
  使用这个列表针对每一个命名的host和子域名去检查所提供的Digital Asset Links JSON 文件。

Confirm the Digital Asset Links files

对于每一website，使用Digital Asset Links API去确认 Digital Asset Links JSON文件格式良好。

https://digitalassetlinks.googleapis.com/v1/statements:list?
source.web.site=https://domain.name:optional_port&
relation=delegate_permission/common.handle_all_urls

Testing a URL intent

 一旦你以及确认了要和app关联的website，也确认了JSON文件是有效的，app以及被安装在设备上。等待20秒去完成异步的验证完成。使用以下命令去验证系统是否以及验证了你的app并且设置了正确的连接处理策略。

adb shell am start -a android.intent.action.VIEW -c android.intent.category.BROWSABLE
-d "http://domain.name:optional_port"

Check link policies

 作为你测试过程的一个部分，你可以检查当前系统对连接处理得设置。使用以下命令去获取当前连接的设备上所有app对连接的处理策略。

adb shell dumpsys package domain-preferred-apps

以下命令能起到一样的作用：

adb shell dumpsys package d

★ Note： 确定你在app安装完成之后至少等待了20秒去让系统完成对website和app的验证。

 命令会返回用户列表或者设备上的概要描述，以下格式的header开头；

App linkages for user 0:

在这个header之后的输出会遵循以下格式去罗列链接处理设置；

Package: com.android.vending
Domains: play.google.com market.android.com
Status: always : 200000002

这个列表表示了domain和app的对于关系；

• Package-Identifies an app by its package name, as declared in its manifest.
• Domains - Shows the full list of hosts whose web links this app handles, using blank spaces as delimiters
  *Status - Shows the current link-handling setting for this app. An app that has passed verification, and whose manifest contains android:autoVerify="true", shows a status of always. The hexadecimal number after this status is related to the Android system's record of the user’s app linkage preferences. This value does not indicate whether verification succeeded.

Note: If a user changes the app link settings for an app before verification is complete, you may see a false positive for a successful verification, even though verification has failed. This verification failure, however, does not matter if the user explicitly enabled the app to open supported links without asking. This is because user preferences take precedence over programmatic verification (or lack of it). As a result, the link goes directly to your app, without showing a dialog, just as if verification had succeeded.

Test example

 For app link verification to succeed, the system must be able to verify your app with all of the websites that you specify in your app’s intent filters, and that meet the criteria for app links. The following example shows a manifest configuration with several app links defined:

<application>

    <activity android:name=”MainActivity”>
        <intent-filter android:autoVerify="true">
            <action android:name="android.intent.action.VIEW" />
            <category android:name="android.intent.category.DEFAULT" />
            <category android:name="android.intent.category.BROWSABLE" />
            <data android:scheme="https" android:host="www.example.com" />
            <data android:scheme="https" android:host="mobile.example.com" />
        </intent-filter>
        <intent-filter>
            <action android:name="android.intent.action.VIEW" />
            <category android:name="android.intent.category.BROWSABLE" />
            <data android:scheme="https" android:host="www.example2.com" />
        </intent-filter>
    </activity>

    <activity android:name=”SecondActivity”>
        <intent-filter>
            <action android:name="android.intent.action.VIEW" />
            <category android:name="android.intent.category.DEFAULT" />
            <category android:name="android.intent.category.BROWSABLE" />
            <data android:scheme="https" android:host="account.example.com" />
        </intent-filter>
    </activity>

      <activity android:name=”ThirdActivity”>
        <intent-filter>
            <action android:name="android.intent.action.VIEW" />
            <category android:name="android.intent.category.DEFAULT" />
            <data android:scheme="https" android:host="map.example.com" />
        </intent-filter>
        <intent-filter>
            <action android:name="android.intent.action.VIEW" />
            <category android:name="android.intent.category.BROWSABLE" />
            <data android:scheme="market" android:host="example.com" />
        </intent-filter>
      </activity>

</application>

 系统会去尝试验证以下host；

www.example.com
mobile.example.com
www.example2.com
account.example.com

 以下列表host系统不会去验证；

map.example.com (it does not have android.intent.category.BROWSABLE)
market://example.com (it does not have either an “http” or “https” scheme)