From 73ff05fb391b8ef60f502814b5ee7ee369c2d4db Mon Sep 17 00:00:00 2001 From: David Friedman Date: Mon, 28 Sep 2015 10:31:30 -0700 Subject: [PATCH] Docs: Migration of app-links doc from Preview to permanent Android 6.0 location Bug: 23623573 Change-Id: Ie5748494af893a872241f21e4137f768ff4ca1ff --- docs/html/training/app-links/index.jd | 344 +++++++++++++------------- docs/html/training/training_toc.cs | 81 ++---- 2 files changed, 196 insertions(+), 229 deletions(-) diff --git a/docs/html/training/app-links/index.jd b/docs/html/training/app-links/index.jd index 3b553ad0ca6d0..18729e9b5b160 100644 --- a/docs/html/training/app-links/index.jd +++ b/docs/html/training/app-links/index.jd @@ -1,4 +1,4 @@ -page.title=App Links +page.title=Handling App Links page.image=images/cards/card-app-linking_2x.png page.keywords=applinking, deeplinks, intents @jd:body @@ -7,11 +7,11 @@ page.keywords=applinking, deeplinks, intents

This lesson teaches you to

    -
  1. Understanding URL Request Handling
    2. -
  2. Create an Intent Handler for URLs
    3. +
  3. Understand URI Request Handling
    4. +
  4. Create an Intent Handler for URIs
  5. Request App Links Verification
  6. Declare Website Associations
    7. -
  7. Testing App Links
    8. +
  8. Test App Links
@@ -19,124 +19,125 @@ page.keywords=applinking, deeplinks, intents

- The M Developer Preview introduces a new option for handling website links. It allows clicked - links to go directly to the website's official app — instead of asking the user to choose - how to handle the link. This feature saves users' 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 each time. + Users following web links on devices are frequently presented with confusing choices. Tapping a + link often results in the system asking the user which app should handle that link. For example, + clicking a URI in an email from a bank might result in a dialog asking the user whether to use + the browser, or the bank's own app, to open the link. Android 6.0 (API level 23) and higher allow + an app to designate itself as the default handler of a given type of link. If the user doesn't + want the app to be the default handler, they can override this behavior from + Settings.

- 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 should 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: + Automatic handling of links requires the cooperation of app developers and website owners. + A developer must configure their app to declare associations with one or more websites, and to + request that the system verify those associations. A website owner must, in turn, provide + that verification by publishing a Digital + Asset Links file. The general steps for creating verified app links are as follows:

    -
  1. Create intent filters within your app for your website URLs.
    2. +
  2. In your app manifest, create intent filters for your website URIs.
  3. Configure your app to request verification of app links.
    4. -
  4. Publish a Digital Asset Links JSON file on your websites.
    5. -
  5. Test that the Android system can verify your app.
    6. +
  6. Publish a Digital Asset Links JSON file on your websites to provide verification.
-

Understanding URL Request Handling

+

Understand URI 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 programmatic request, the Android system determines what app - is used to handle the intent. The system uses these criteria, in order, to determine how to handle - the request: + The app links feature allows your app to become the default handler for the website URIs you + specify, as long as the user has not already chosen a default app to handle that URI pattern. + When a clicked link or programmatic request invokes a web URI intent, the Android system + uses the following criteria, in descending order, to determine how to handle the request:

  1. - The user has set up a matching app link association. If the user has designated - an app to handle app links, the system passes the web URI request to that app. The user sets - this association by opening - Settings > Apps > Configure apps (gear icon) > App links, and - then selecting an app to use and configuring its App links property to the - Open in this app option. + The 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. A user can set this + association in one of two ways: clicking Always when selecting an app + from an app-selection dialog; or, opening Settings > Apps > (gear icon) + > App links, selecting an app to use, and setting the app's + App links property to the Open in this app option.
  2. - The user has not set up an association, and there is 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. + The user has set no association, and there is one 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 automatically passes the request to that app.
  3. - The user has not set up an association, and there are 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. + The user has set no association, and there are multiple supporting apps: If + there are multiple apps declaring support for the web URI pattern, the system displays an + app-selection dialog, prompting the user to select the most appropriate app.

- In the second case, 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. + In case 2, if the user has newly installed the app, and the system has + verified it as a handler for this type of link, the system sets the app as the default handler. In + the other two cases, the presence of a verified app link handler has no effect on system behavior.

-

Create an Intent Handler for URLs

+

Create an Intent Handler for URIs

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 a web link + declare the same 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. + using the criteria described in Understanding URI Request Handling.

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 + patterns that your app handles. The following example 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>
+<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 this example, intent filters for app links must declare an {@code android:scheme} - value of {@code http}, {@code https}, or both. The filter should not declare + As this example shows, intent filters for app links must declare an {@code android:scheme} + value of {@code http}, {@code https}, or both. The filter must 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, - 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. + 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 URIs, you must + also request that the system verify this connection. + The next section explains how to implement this verification.

Request App Links Verification

- In addition to declaring an association between your app and a website by 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's 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. + In addition to using intent filters to declare an association between your app and a website, + your manifest must also include an additional declaration for requesting automatic verification. + When this declaration is present, the Android system attempts to verify your app after + installation. If the verification succeeds, and the user has not set an alternate + preference for handling your website URIs, the system automatically routes those URI requests to + your app.

- The system performs app link verifications by comparing the hostnames in the data elements of + 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 @@ -157,7 +158,7 @@ page.keywords=applinking, deeplinks, intents <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.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" /> @@ -167,9 +168,9 @@ page.keywords=applinking, deeplinks, intents

- When the {@code android:autoVerify} attribute is set, the system attempts to verify all hosts - associated with web URIs 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 + When the {@code android:autoVerify} attribute is present, installing your app causes the system + to attempt to verify all hosts associated with the web URIs in all of your app's intent filters. + 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.

@@ -177,11 +178,11 @@ page.keywords=applinking, deeplinks, intents

Supporting app linking for multiple hosts

- The system must be able to verify each host specified in the data elements of the app’s web URI - intent filters 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 + The system must be able to verify every 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 URI + patterns defined in the app's 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}:

@@ -189,7 +190,7 @@ page.keywords=applinking, deeplinks, intents 
 <application>
 
-  <activity android:name="MainActivity">
+  <activity android:name=”MainActivity”>
     <intent-filter android:autoVerify="true">
       <action android:name="android.intent.action.VIEW" />
       <category android:name="android.intent.category.DEFAULT" />
@@ -198,7 +199,7 @@ page.keywords=applinking, deeplinks, intents
       <data android:scheme="https" android:host="www.domain1.com" />
     </intent-filter>
   </activity>
-  <activity android:name="SecondActivity">
+  <activity android:name=”SecondActivity”>
     <intent-filter>
       <action android:name="android.intent.action.VIEW" />
       <category android:name="android.intent.category.DEFAULT" />
@@ -207,7 +208,7 @@ page.keywords=applinking, deeplinks, intents
     </intent-filter>
   </activity>
 
-</application>
+</application
@@ -216,7 +217,7 @@ page.keywords=applinking, deeplinks, intents

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 a separate {@code assetlink.json} file on each subdomain. For example, an + hosts, you must host a 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 @@ -225,7 +226,7 @@ page.keywords=applinking, deeplinks, intents 

 <application>
-  <activity android:name="MainActivity">
+  <activity android:name=”MainActivity”>
     <intent-filter android:autoVerify="true">
       <action android:name="android.intent.action.VIEW" />
       <category android:name="android.intent.category.DEFAULT" />
@@ -247,47 +248,50 @@ page.keywords=applinking, deeplinks, intents
 

 
 
-  https://domain[:optional_port]/.well-known/assetlinks.json
+https://domain[:optional_port]/.well-known/assetlinks.json
 

 
 

-  Important: With M Preview 3 and the Android 6.0 (API level 23) release, the JSON
-  file is verified through 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.
+  Important: The system verifies the JSON file via the encrypted HTTPS protocol.
+  Make sure that your hosted file is accessible over an HTTPS connection, regardless of whether
+  your app's intent filter includes {@code https}.
 

 
 

   A Digital Asset Links JSON file indicates the Android apps that are associated with the website.
-  The JSON file identifies associated apps with the following fields:
+  The JSON file uses the following fields to identify associated apps:
 

 
 
 
 

-  The following example {@code assetlinks.json} file grants link opening rights to a
-  {@code com.example} Android application:
+  The following example {@code assetlinks.json} file grants link-opening rights to a
+  {@code com.example} Android 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"]
-    }
-  }]
+[{
+  "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"]
+  }
+}]
 

 
 
@@ -296,7 +300,7 @@ page.keywords=applinking, deeplinks, intents
 

   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
+  with two apps, separately, and resides at
   https://www.example.com/.well-known/assetlinks.json:
 

 
@@ -322,10 +326,8 @@ page.keywords=applinking, deeplinks, intents

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

@@ -340,7 +342,8 @@ page.keywords=applinking, deeplinks, intents

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: + association of domain1 and domain2 with app1. The first listing shows the association of + domain1 with app1: 

@@ -357,6 +360,9 @@ https://www.domain1.com/.well-known/assetlinks.json
 }]
+

The next listing shows the association of domain2 with app1. Only the very last line, which +specifies the URL, is different:

+ 
 https://www.domain2.com/.well-known/assetlinks.json
 
@@ -371,13 +377,11 @@ https://www.domain2.com/.well-known/assetlinks.json
 }]
- - -

Testing App Links

+

Test App Links

When implementing the app linking feature, you should test the linking functionality to - make sure that your app can be successfully associated with your websites and handle URL requests + make sure the system can associate your app with your websites, and handle URI requests, as you expect.

@@ -386,8 +390,8 @@ https://www.domain2.com/.well-known/assetlinks.json

When testing, you should confirm the list of associated hosts that the system should verify - for your app. Make a list of all web URIs in intent-filters in your manifest that - include all of the following: + for your app. Make a list of all web URIs whose corresponding intent filters include the following + attributes and elements:

-
  • -
    - Working with System Permissions -
    - -
    • -
  • @@ -836,7 +811,7 @@ include the action bar on devices running Android 2.1 or higher."
    Building Apps with
    - Contacts & Sign-In + User Info & Sign-In
    • + +
    • + +
  • - Specifying App Content for Indexing + Specifying App Content for Indexing
    • - - + + + +
  • +
    + Handling App Links +
    +
    • - - +
  • @@ -1413,6 +1401,7 @@ results."