From 94fc625cf19bae6cfeef12bd1577b6370725e674 Mon Sep 17 00:00:00 2001 From: Joe Fernandez Date: Fri, 14 Aug 2015 03:00:27 -0700 Subject: docs: App link doc update for M Preview 3 Change-Id: I9a8843bb2209f9ac12d5d0946dda1e3bdd6f1947 --- docs/html/preview/features/app-linking.jd | 556 +++++++++++++++++++++++++++--- 1 file changed, 502 insertions(+), 54 deletions(-) diff --git a/docs/html/preview/features/app-linking.jd b/docs/html/preview/features/app-linking.jd index 5592323..b8fb300 100644 --- a/docs/html/preview/features/app-linking.jd +++ b/docs/html/preview/features/app-linking.jd @@ -7,61 +7,295 @@ page.keywords=applinking, deeplinks, intents

In this document

    -
  1. Declare a Website Association
    2. -
  2. Request App Link Verification
    3. -
  3. Managing App Link Settings
    4. +
  4. Understanding URL Request Handling
    5. +
  5. Create an Intent Handler for URLs
    6. +
  6. Request App Links Verification
    7. +
  7. Declare Website Associations
    8. +
  8. Testing App Links
+ +

+ 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. +

+ +

+ 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: +

+ +
    +
  1. Create intent filters within your app for your website URLs
    2. +
  2. Configure your app to request verification of app links
    3. +
  3. Publish a Digital Asset Links JSON file on your websites
    4. +
+ +

Understanding URL Request Handling

+ +

+ 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: +

+ +
    +
  1. + User has set app link associations: If the user has designated an app to + handle app links, the system passes the web URI request to that app. Users set this association + by opening Settings > Apps > Configure apps (gear icon) > App links, + then selecting an app to use and configuring it's App links property to the + Open in this app option. +
    2. + +
  2. + No association set by user and a single supporting app: If the user + has not set a preference that matches the web URI request, and there is only one app declaring + support for the intent’s URI pattern, the system passes the request to that app. +
    3. + +
  3. + No association set by user and multiple supporting apps: If there is + no explicit user preference and there are multiple apps declaring support for the web URI + pattern, the system prompts the user to select one of the available apps +
    4. +
+ +

+ 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. +

+ + +

Create an Intent Handler for URLs

+ +

+ 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>
+
+

- 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. + 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.

- 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. + 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.

-

Declare a Website Association

+

Request App Links Verification

+ +

+ 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. +

- 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 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.

-
http://<domain>:<optional port>/.well-known/statements.json
+ +

Enabling automatic verification

+ +

+ 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. +

+ + +

Supporting app linking for multiple hosts

+ +

+ 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
+
+ + +

Supporting app linking for multiple subdomains

+ +

+ 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>
+
+ + +

Declare Website Associations

+ +

+ 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:

- 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"]
+    }
+  }]
+
+ + +

Associating a website with multiple apps

+ +

+ 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. +

+ + +

Associating multiple websites with a single app

- 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: + 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: 

-<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://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"]
+  }
+}]
+
+ + + +

Testing App Links

+ +

+ 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. +

+ + +

Confirm the list of hosts to verify

+ +

+ 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. +

+ + +

Confirm the Digital Asset Links files

+ +

+ For each website, confirm that the Digital Asset Links JSON file is properly hosted and + defined by using the Digital Asset Links API: +

+ +
+https://digitalassetlinks.googleapis.com/v1/statements:list?
+   source.web.site=https://<domain1>:<port>&
+   relation=delegate_permission/common.handle_all_urls
+
+ + +

Testing a web URI intent

+ +

+ 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>"
+ + +

- 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. + 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: 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: 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: +

-

Managing App Link Settings

+
+App linkages for user 0:
+

- 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. + 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: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. +

+ + + +

Test example

+ +

+ 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)
+
-- cgit v1.1