- The Android Intent system is a flexible mechanism to enable apps to handle content and requests. - Multiple apps may declare matching URI patterns in their intent filters. When a user clicks on a - web link that does not have a default launch handler, the platform may show a dialog for the user - to select from a list of apps that have declared matching intent filters. + The M Developer Preview introduces a new option for handling web site links, allowing clicked + links to go directly to the website's official app, instead of asking the user to chose how to + handle the link. This feature saves the user time and helps developers deliver a better + experience. Users can also select whether an app should always open specific types of links + automatically or prompt the user each time.
- The Android M Developer Preview introduces support for App Links, which improves upon existing - link handling by allowing app developers to associate an app with a web domain they own. When - developers create this association, the platform can automatically determine the default app used - to handle a particular web link and skip asking users. + Handling links automatically requires the cooperation of app developers and website owners. + Developers must configure their apps to declare connections with websites and request + verification. Website owners can publish a + Digital Asset Links file + to allow Android to verify the association of apps with their sites. The general steps for + creating verified app links are as follows:
+- Website owners must declare associations with apps to establish an app link. The site owner - declares the relationship to an app by hosting a JSON file, named {@code statements.json}, at the - well-known location on the domain: + The app links feature allows your app to become the default handler for your website URLs, as + long as the user has not already chosen an app to handle that URL pattern. When a web URI intent + is invoked through a clicked link or programatic request, the Android system determines what app + is used to handle the intent. The system use these criteria, in order, to determine how to handle + the request:
-http://<domain>:<optional port>/.well-known/statements.json+
+ In case #2 (no user setting and no other app handlers), if an app is newly installed and verified + as a handler for this type of link, the system sets it as the default handler. In the other two + cases, the system behavior is the same, regardless of the presence of a verified app link + handler. +
+ + ++ App links are based on the Intent + framework, which enables apps to handle requests from the system or other apps. Multiple apps may + declare matching web link URI patterns in their intent filters. When a user clicks on a web link + that does not have a default launch handler, the platform selects an app to handle the request, + based on the criteria described in the previous section. +
+ ++ To enable your app to handle links, use intent filters in your app manifest to declare the URI + patterns to be handled by your app. The following sample code shows an intent filter that can + handle links to {@code http://www.android.com} and {@code https://www.android.com}: +
+ ++ <activity ...> + <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="http" /> + <data android:scheme="https" /> + <data android:host="www.android.com" /> + </intent-filter> + </activity> ++ +
+ As shown in the example above, intent filters for app links must declare an {@code android:scheme} + value of either {@code http} or {@code https}, or both. The filter should not declare + any other schemes. The filter must also include the {@code android.intent.action.VIEW}; and + {@code android.intent.category.BROWSABLE} category names. +
+ ++ This manifest declaration defines the connection between your app and a website. However, in + order to have the system treat your app as the default handler for a set of URLs, you must + also request that the system verify this connection, which is explained in the next section. +
+ + ++ In addition to declaring an association between your app and a web site using intent filters, + your app must also request automatic verification with an additional manifest declaration. When + this declaration is set, the Android system attempts to verify your app after it is installed. + If the verification succeeds, and the user has not set a preference for your website URLs, the + system automatically routes those URL requests to your app. +
+ ++ The system performs app link verifications by comparing the host names in the data elements of + the app’s intent filters against the Digital Asset Links files ({@code assetlinks.json}) hosted + on the respective web domains. To enable the system to verify a host, make sure that your intent + filter declarations include the {@code android.intent.action.VIEW} intent action and {@code + android.intent.category.BROWSABLE} intent category. +
+ + ++ To enable link handling verification for your app, set the {@code android:autoVerify} attribute to + {@code true} on at least one of the web URI intent filters in your app manifest, as shown in the + following manifest code snippet: +
+ ++<activity ...> + + <intent-filter android:autoVerify="true"> + <action android:name="android.intent.action.VIEW" /> + <category android:name="android.intent.category.DEFAULT"gt; + <category android:name="android.intent.category.BROWSABLE" /> + <data android:scheme="http" android:host="www.android.com" /> + <data android:scheme="https" android:host="www.android.com" /> + </intent-filter> + +</activity> ++ +
+ When the {@code android:autoVerify} attribute is set, the system attempts to verify all hosts + associated with web URI’s in all of your app's intent filters when the app is installed. The + system treats your app as the default handler for the specified URI pattern only if it + successfully verifies all app link patterns declared in your manifest. +
+ + ++ The system must be able to verify each host specified in the app’s web URI intent filters’ data + elements against the Digital Asset Links files hosted on the respective web domains. If any + verification fails, the app is not verified to be a default handler for any of the web URL + patterns defined in its intent filters. For example, an app with the following intent filters + would fail verification if an {@code assetlinks.json} file were not found at both + {@code https://www.domain1.com/.well-known/assetlinks.json} and + {@code https://www.domain2.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="http" android:host="www.domain1.com" /> + <data android:scheme="https" android:host="www.domain1.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="www.domain2.com" /> + </intent-filter> + </activity> + +</application ++ + +
+ The Digital Asset Links protocol treats subdomains as unique, separate hosts. If your intent + filter lists both the {@code www.example.com} and {@code mobile.example.com} subdomains as + schemes, you must host separate {@code assetlink.json} file on each subdomain. For example, an + app with the following intent filter declaration would pass verification only if the website + owner published valid {@code assetlinks.json} files at both + {@code https://www.example.com/.well-known/assetlinks.json} and + {@code https://mobile.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="http" android:host="www.example.com" /> + <data android:scheme="https" android:host="mobile.example.com" /> + </intent-filter> + </activity> +</application> ++ + +
+ For app link verification to be successful, website owners must declare associations + with apps. A site owner declares the relationship to an app by hosting a Digital Asset Links JSON + file, with the name {@code assetlinks.json}, at the following well-known location on the domain: +
+ ++ https://domain[:optional_port]/.well-known/assetlinks.json +
- Note: - During the M Developer Preview period, the JSON file is verified via http protocol. For - the official release of the platform, the file is verified over encrypted, https protocol. + Important: With M Preview 3 and the Android 6.0 (API level 23) release, the JSON + file is verified via the encrypted HTTPS protocol. Make sure that your hosted file can be + accessed over an HTTPS connection, regardless of whether your app's intent filter declares an + {@code android:scheme} setting of {@code http}, {@code https} or both.
- This JSON file indicates the Android app that should be used as the default handler for the URLs - under this domain. It identifies the app based on these fields: + A Digital Asset Links JSON file indicates the Android apps that are associated with the web site. + The JSON file identifies associated apps with the following fields:
keytool -list -v -keystore my-release-key.keystore+ This field supports multiple fingerprints, which can be used to support different versions + of your app, such as debug and production builds.
- The following file listing shows an example of the contents and format of a - {@code statements.json} file: + The following example {@code assetlinks.json} file grants link opening rights to a + {@code com.example} Android application: +
+ +
+ [{
+ "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"]
+ }
+ }]
+
+
+
+
+ A website can declare associations with multiple apps within the same {@code assetlinks.json}
+ file. The following file listing shows an example of a statement file that declares association
+ with two, separate apps and is hosted at
+ https://www.example.com/.well-known/assetlinks.json:
@@ -69,55 +303,269 @@ page.keywords=applinking, deeplinks, intents
"relation": ["delegate_permission/common.handle_all_urls"],
"target": {
"namespace": "android_app",
- "package_name": "<package name>",
- "sha256_cert_fingerprints": ["6C:EC:C5:0E:34:AE....EB:0C:9B"]
+ "package_name": "example.com.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": "example.com.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"]
+ }
+}]
+
+
++ When multiple apps handle links to the same host, the system determines which one to use for + a given link based on the intent filters defined in each app’s manifest. Different apps may + handle links for different resources under the same web host. For example, app1 may + declare an intent filter for {@code https://example.com/articles}, and app2 may declare + an intent filter for {@code https://example.com/videos}. +
+ ++ Note: Multiple apps associated with a domain may be signed with the same or + different certificates. +
+ + ++ Multiple websites can declare associations with the same app in their respective {@code + assetlinks.json} files. The following file listings show an example of how to declare the + association of domain1 and domain2 with app1: +
+ +
+https://www.domain1.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"]
+ }
+}]
+
+
+
+https://www.domain2.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"]
}
}]
-- An app can request that the platform automatically verify any app links defined by the host names - in the data elements of its intent filters against the {@code statements.json} files hosted on - the respective web domains. To request app link verification, add an {@code android:autoVerify} - attribute to each desired intent filter in the manifest, as shown in the following manifest code - snippet: + When implementing the app linking feature, you should test the linking functionality to + make your app can be successfully associated with your websites and handle URL requests + as you expect. +
+ + ++ When testing, you should confirm the list of associated hosts that the system should verify + for your app. Make a list of all web URI’s in intent-filters in your manifest that + includes the following: +
+ ++ Use this list to check that a Digital Asset Links JSON file is provided on each named host + and subdomain. +
+ + ++ For each website, confirm that the Digital Asset Links JSON file is properly hosted and + defined by using the Digital Asset Links API:
-<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.android.com" /> - <data android:scheme="https" android:host="www.android.com" /> - </intent-filter> -</activity> +https://digitalassetlinks.googleapis.com/v1/statements:list? + source.web.site=https://<domain1>:<port>& + relation=delegate_permission/common.handle_all_urls ++ + +
+ Once you have confirmed the list of websites to associate with your app, and you have confirmed + that the hosted JSON file is valid, install the app on your device. Wait at least 20 seconds for + the asynchronous verification process to complete. Use the following command to check + if the system verified your app and set the correct link handling policies: +
+ ++adb shell am start -a android.intent.action.VIEW \ + -c android.intent.category.BROWSABLE \ + -d "http://<domain1>:<port>" ++ + +
+ As part of your testing process, you can check the current system settings for link handling. + Use the following command to get a listing of link-handling policies for all applications: +
+ ++ adb shell dumpsys package domain-preferred-apps + --or-- + adb shell dumpsys package d ++ +
+ Note: Make sure you wait at least 20 seconds after installation of your app to + allow for the system to complete the verification process. +
+ ++ The command returns a listing of each user or profile defined on the device, + indicated by a header in the following format: +
+ ++App linkages for user 0:
- When the {@code android:autoVerify} attribute is present in an app manifest, the platform - attempts to verify app links when the app is installed. If the platform cannot successfully - verify the app links, the app is not set as the preferred app to handle the web links. The next - time a user opens one of the links, the platform falls back to presenting the user with a - dialog. + Following this heading, the output lists the link-handling settings for that user in this format:
++Package: com.android.vending +Domains: play.google.com market.android.com +Status: always : 200000002 ++ +
This listing indicates the what apps are associated with what domains for that user, as + described below:
+ +- Note: In testing, there is a potential for a false positive if verfication - fails, but the user has explicitly enabled the app to open supported links without asking, using - the system Settings app. In this case, no dialog is shown and the link goes directly to your - app, but only because of the user setting, and not because verification succeeded. + Note:It is possible for a user to change the app link settings for an app + before the verification operation has completed. If this + situation occurs, you may see a false positive for a successful verification, even though + verification has failed. However, the user has already explicitly enabled the app to open + supported links without asking. In this case, no dialog is shown and the link goes directly to + your app, but only because explicit user preferences take precedence.
-- Users can change app link settings so URLs are handled the way they prefer. You can review and - manage app links in the system Settings app, under Settings > Apps > App Info > - Open by default. + For app link verification to succeed, the system must be able to verify your app with all of + the websites referenced in your app’s intent filters, that meet the criteria for app links. + The following example manifest snippet shows app 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="http" 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="http" 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="http" 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="http" 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> ++ +
+ The list of hosts that the platform would attempt to verify from the above manifest is: +
+ ++ www.example.com + mobile.example.com + www.example2.com + account.example.com ++ +
+ The list of hosts that the platform would not attempt to verify from the above manifest is: +
+ ++ map.example.com (it does not have android.intent.category.BROWSABLE) + market://example.com (it does not have either an “http” or “https” scheme) +