am 50fe9a3a: am 5e95f0e5: am ad7cf3af: Merge "docs: Added training doc for app indexing (aka Calypso)." into klp-docs
* commit '50fe9a3a':
docs: Added training doc for app indexing (aka Calypso).
<li><a href="#adding-filters">Add Intent Filters for Your Deep Links</a></li>
<li><a href="#handling-intents">Read Data from Incoming Intents</a></li>
<li><a href="#testing-filters">Test Your Deep Links</a></li>
</ol>
<h2>You should also read</h2>
<ul>
<li><a href="{@docRoot}guide/components/intents-filters.html">Intents and Intent Filters</a></li>
<li><a href="{@docRoot}training/basics/intents/filters.html">Allow Other Apps to Start Your Activity</a></li>
</ul>
</div>
</div>
<p>To enable Google to crawl your app content and allow users to enter your app
from search results, you must add intent filters for the relevant
activities in your app manifest. These intent filters allow
<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>
<h2 id="adding-filters">Add Intent Filters for Your Deep Links</h2>
<p>To create a deep link to your app content, add an intent filter that
contains these elements and attribute values in your manifest:</p>
<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.
<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>
<!-- Accepts URIs that begin with "example://gizmos” -->
<data android:scheme="example"
android:host="gizmos" />
<!-- Accepts URIs that begin with "http://www.example.com/gizmos” -->
<data android:scheme="http"
android:host="www.example.com"
android:pathPrefix="gizmos" />
</intent-filter>
</activity>
</pre>
<p>Once you've added intent filters with URIs for activity content to your app
manifest, Android is able to route any {@link android.content.Intent}
that has matching URIs to your app at runtime.</p>
<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>
<h2 id="handling-intents">Read Data from Incoming Intents</h2>
<p>Once the system starts your activity through an intent filter, you can
use data provided by the {@link android.content.Intent} to determine what you need to render. Call the {@link android.content.Intent#getData()} and
{@link android.content.Intent#getAction()} methods to retrieve the data and
action associated with the incoming {@link android.content.Intent}. You can
call these methods at any time during the lifecycle of the activity, but you
should generally do so during early callbacks such as {@link
android.app.Activity#onCreate(android.os.Bundle) onCreate()} or
{@link android.app.Activity#onStart()}.</p>
<p>Here’s a snippet that shows how to retrieve data from an
{@link android.content.Intent}:</p>
<pre>
@Override
public void onCreate(Bundle savedInstanceState) {
super.onCreate(savedInstanceState);
setContentView(R.layout.main);
Intent intent = getIntent();
String action = intent.getAction();
Uri data = intent.getData();
}
</pre>
<p>Follow these best practices to improve the user's experience:</p>
<ul>
<li>The deep link should take users directly to the content,
without any prompts, interstitial pages, or logins. Make sure that users can
see the app content even if they never previously opened the application.
It is okay to prompt users on subsequent interactions or when they open the app
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>
<li>Follow the design guidance described in
<a href="{@docRoot}design/patterns/navigation.html">Navigation with Back and Up</a>
so that your app matches users' expectations for backward navigation after
they enter your app through a deep link.
</li>
</ul>
<h2 id="testing-filters">Test Your Deep Links</h2>
<p>You can use the <a href="{@docRoot}tools/help/adb.html">Android Debug
Bridge</a> with the activity manager (am) tool to test that the intent filter
URIs you specified for deep linking resolve to the correct app activity. You
can run the adb command against a device or an emulator.</p>
<p>The general syntax for testing an intent filter URI with adb is:</p>
<pre>
$ adb shell am start
-W -a android.intent.action.VIEW
-d <URI> <PACKAGE>
</pre>
<p>For example, the command below tries to view a target app activity that
<p>Google's web crawling bot (<a href="https://support.google.com/webmasters/answer/182072?hl=en" class="external-link" target="_blank">Googlebot</a>), which crawls and indexes web sites
for the Google search engine, can also index content in your Android app.
By opting in, you can allow Googlebot to crawl the content in the APK
through the Google Play Store to index the app content. To indicate which app
content you’d like Google to index, simply add link elements either to
your existing <a href="https://support.google.com/webmasters/answer/156184?hl=en" class="external-link" target="_blank">Sitemap</a> file or in the {@code <head>} element of each web
page in your site, in the same way as you would for web pages.</p>
<p class="note"><strong>Note: </strong>
Currently, the Google Search app indexing capability is restricted to
English-only Android apps from developers participating in the early adopter
program. You can sign up to be a participant by submitting the <a
<h2 id="robots">Allow Google to Crawl URLs Requested By Your App</h2>
<p>Typically, you control how Googlebot crawls publicly accessible URLs on
your site by using a <a href="https://developers.google.com/webmasters/control-crawl-index/docs/robots_txt" class="external-link" target="_blank">{@code robots.txt}</a>
file. When Googlebot indexes your app content, your app might make HTTP
requests as part of its normal operations. However, these requests will
appear to your servers as originating from Googlebot. Therefore, you must
configure your server's {@code robots.txt} file properly to allow these
requests.</p>
<p>For example, the following {@code robots.txt} directive shows how you might
allow access to a specific directory in your web site (for example,
{@code /api/}) that your app needs to access, while restricting Googlebot's
access to other parts of your site.</p>
<pre>
User-Agent: Googlebot
Allow: /api/
Disallow: /
</pre>
<p>To learn more about how to modify {@code robots.txt} to control web
crawling, see the <a href="https://developers.google.com/webmasters/control-crawl-index/docs/getting_started" class="external-link" target="_blank">Controlling Crawling
<li><a href="http://insidesearch.blogspot.com/2013/12/the-power-of-search-now-across-apps.html" class="external-link" target="_blank">The power of Search, now across apps (blog post)</a></li>
