1 page.title=Enabling Deep Links for App Content 2 trainingnavtop=true 3 4 @jd:body 5 6 <!-- This is the training bar --> 7 <div id="tb-wrapper"> 8 <div id="tb"> 9 10 <h2>This lesson teaches you to</h2> 11 <ol> 12 <li><a href="#adding-filters">Add Intent Filters for Your Deep Links</a></li> 13 <li><a href="#handling-intents">Read Data from Incoming Intents</a></li> 14 <li><a href="#testing-filters">Test Your Deep Links</a></li> 15 </ol> 16 17 <h2>You should also read</h2> 18 <ul> 19 <li><a href="{@docRoot}guide/components/intents-filters.html">Intents and Intent Filters</a></li> 20 <li><a href="{@docRoot}training/basics/intents/filters.html">Allow Other Apps to Start Your Activity</a></li> 21 </ul> 22 23 </div> 24 </div> 25 26 <p>To enable Google to crawl your app content and allow users to enter your app 27 from search results, you must add intent filters for the relevant 28 activities in your app manifest. These intent filters allow 29 <em>deep linking</em> to the content in any of your activities. For example, the user might click on a deep link to view a page within a shopping app that describes a product offering that the user is searching for.</p> 30 31 <h2 id="adding-filters">Add Intent Filters for Your Deep Links</h2> 32 <p>To create a deep link to your app content, add an intent filter that 33 contains these elements and attribute values in your manifest:</p> 34 <dl> 35 <dt><a href="{@docRoot}guide/topics/manifest/action-element.html">{@code <action>}</a></dt> 36 <dd>Specify the {@link android.content.Intent#ACTION_VIEW} intent action so 37 that the intent filter can be reached from Google Search.</dd> 38 <dt><a href="{@docRoot}guide/topics/manifest/data-element.html">{@code <data>}</a></dt> 39 <dd>Add one or more <a href="{@docRoot}guide/topics/manifest/data-element.html">{@code <data>}</a> tags, where each tag represents a URI format that resolves to the activity. At minimum, the <a href="{@docRoot}guide/topics/manifest/data-element.html">{@code <data>}</a> tag must include the <a href="{@docRoot}guide/topics/manifest/data-element.html#scheme">{@code android:scheme}</a> attribute. 40 <p>You can add additional attributes to further refine the type of URI that the activity accepts. For example, you might have multiple activities that accept similar URIs, but which differ simply based on the path name. In this case, use the <a href="{@docRoot}guide/topics/manifest/data-element.html#path">{@code android:path}</a> attribute or its variants ({@code pathPattern} or {@code pathPrefix}) to differentiate which activity the system should open for different URI paths.</p></dd> 41 <dt><a href="{@docRoot}guide/topics/manifest/category-element.html">{@code <category>}</a></dt> 42 <dd>Include the {@link android.content.Intent#CATEGORY_BROWSABLE BROWSABLE} 43 category. The {@link android.content.Intent#CATEGORY_BROWSABLE BROWSABLE} 44 category is required in order for the intent filter to be accessible from a web 45 browser. Without it, clicking a link in a browser cannot resolve to your app. 46 The {@link android.content.Intent#CATEGORY_DEFAULT DEFAULT} category is 47 optional, but recommended. Without this category, the activity can be started 48 only with an explicit intent, using your app component name. 49 </dd> 50 </dl> 51 52 <p>The following XML snippet shows how you might specify an intent filter 53 in your manifest for deep linking. The URIs {@code example://gizmos} and 54 {@code http://www.example.com/gizmos} both resolve to this activity.</p> 55 56 <pre> 57 <activity 58 android:name="com.example.android.GizmosActivity" 59 android:label="@string/title_gizmos" > 60 <intent-filter android:label="@string/filter_title_viewgizmos"> 61 <action android:name="android.intent.action.VIEW" /> 62 <category android:name="android.intent.category.DEFAULT" /> 63 <category android:name="android.intent.category.BROWSABLE" /> 64 <!-- Accepts URIs that begin with "http://www.example.com/gizmos --> 65 <data android:scheme="http" 66 android:host="www.example.com" 67 android:pathPrefix="/gizmos" /> 68 <!-- note that the leading "/" is required for pathPrefix--> 69 <!-- Accepts URIs that begin with "example://gizmos --> 70 <data android:scheme="example" 71 android:host="gizmos" /> 72 73 </intent-filter> 74 </activity> 75 </pre> 76 77 <p>Once you've added intent filters with URIs for activity content to your app 78 manifest, Android is able to route any {@link android.content.Intent} 79 that has matching URIs to your app at runtime.</p> 80 81 <p class="note"> 82 <strong>Note:</strong> Intent filters may only contain a single {@code data} element 83 for a URI pattern. Create separate intent filters to capture additional URI patterns. 84 </p> 85 86 <p>To learn more about defining intent filters, see <a href="{@docRoot}training/basics/intents/filters.html">Allow Other Apps to Start Your Activity</a>.</p> 87 88 <h2 id="handling-intents">Read Data from Incoming Intents</h2> 89 <p>Once the system starts your activity through an intent filter, you can 90 use data provided by the {@link android.content.Intent} to determine what you need to render. Call the {@link android.content.Intent#getData()} and 91 {@link android.content.Intent#getAction()} methods to retrieve the data and 92 action associated with the incoming {@link android.content.Intent}. You can 93 call these methods at any time during the lifecycle of the activity, but you 94 should generally do so during early callbacks such as {@link 95 android.app.Activity#onCreate(android.os.Bundle) onCreate()} or 96 {@link android.app.Activity#onStart()}.</p> 97 <p>Heres a snippet that shows how to retrieve data from an 98 {@link android.content.Intent}:</p> 99 <pre> 100 @Override 101 public void onCreate(Bundle savedInstanceState) { 102 super.onCreate(savedInstanceState); 103 setContentView(R.layout.main); 104 105 Intent intent = getIntent(); 106 String action = intent.getAction(); 107 Uri data = intent.getData(); 108 } 109 </pre> 110 <p>Follow these best practices to improve the user's experience:</p> 111 <ul> 112 <li>The deep link should take users directly to the content, 113 without any prompts, interstitial pages, or logins. Make sure that users can 114 see the app content even if they never previously opened the application. 115 It is okay to prompt users on subsequent interactions or when they open the app 116 from the Launcher. This is the same principle as the <a href="https://support.google.com/webmasters/answer/74536?hl=en" class="external-link" target="_blank">first click free</a> experience for web sites.</li> 117 <li>Follow the design guidance described in 118 <a href="{@docRoot}design/patterns/navigation.html">Navigation with Back and Up</a> 119 so that your app matches users' expectations for backward navigation after 120 they enter your app through a deep link. 121 </li> 122 </ul> 123 124 <h2 id="testing-filters">Test Your Deep Links</h2> 125 <p>You can use the <a href="{@docRoot}tools/help/adb.html">Android Debug 126 Bridge</a> with the activity manager (am) tool to test that the intent filter 127 URIs you specified for deep linking resolve to the correct app activity. You 128 can run the adb command against a device or an emulator.</p> 129 <p>The general syntax for testing an intent filter URI with adb is:</p> 130 <pre> 131 $ adb shell am start 132 -W -a android.intent.action.VIEW 133 -d <URI> <PACKAGE> 134 </pre> 135 <p>For example, the command below tries to view a target app activity that 136 is associated with the specified URI.</p> 137 <pre> 138 $ adb shell am start 139 -W -a android.intent.action.VIEW 140 -d "example://gizmos" com.example.android 141 </pre> 142
