docs: Added training doc for app indexing (aka Calypso).

page.title=Enabling Deep Links for App Content

trainingnavtop=true

@jd:body

<!-- This is the training bar -->

<div id="tb-wrapper">

<div id="tb">

<h2>This lesson teaches you to</h2>

<ol>

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

<dl>

<dt><a href="{@docRoot}guide/topics/manifest/action-element.html">{@code &lt;action&gt;}</a></dt>

<dd>Specify the {@link android.content.Intent#ACTION_VIEW} intent action so

  that the intent filter can be reached from Google Search.</dd>

<dt><a href="{@docRoot}guide/topics/manifest/data-element.html">{@code &lt;data&gt;}</a></dt>

<dd>Add one or more <a href="{@docRoot}guide/topics/manifest/data-element.html">{@code &lt;data&gt;}</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 &lt;data&gt;}</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>

<dt><a href="{@docRoot}guide/topics/manifest/category-element.html">{@code &lt;category&gt;}</a></dt>

<dd>Include the {@link android.content.Intent#CATEGORY_BROWSABLE BROWSABLE}

category. The {@link android.content.Intent#CATEGORY_BROWSABLE BROWSABLE}

category is required in order for the intent filter to be accessible from a web

browser. Without it, clicking a link in a browser cannot resolve to your app.

The {@link android.content.Intent#CATEGORY_DEFAULT DEFAULT} category is

optional, but recommended. Without this category, the activity can be started

only with an explicit intent, using your app component name.

</dd>

</dl>

<p>The following XML snippet shows how you might specify an intent filter

in your manifest for deep linking. The URIs {@code “example://gizmos”} and

{@code “http://www.example.com/gizmos”} both resolve to this activity.</p>

<pre>

<activity

    android:name="com.example.android.GizmosActivity"

    android:label="@string/title_gizmos" >

    <intent-filter android:label="@string/filter_title_viewgizmos">

        <action android:name="android.intent.action.VIEW" />

        <category android:name="android.intent.category.DEFAULT" />

        <category android:name="android.intent.category.BROWSABLE" />

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

is associated with the specified URI.</p>

<pre>

$ adb shell am start

        -W -a android.intent.action.VIEW

        -d "example://gizmos" com.example.android

</pre>

page.title=Specifying App Content for Indexing

trainingnavtop=true

@jd:body

<!-- This is the training bar -->

<div id="tb-wrapper">

<div id="tb">

<h2>This lesson teaches you to</h2>

<ol>

  <li><a href="#sitemap">Add Deep Links in Your Sitemap</a></li>

  <li><a href="#webpages">Add Deep Links in Your Web Pages</a></li>

  <li><a href="#robots">Allow Google to Crawl URLs Requested By Your App</a></li>

</ol>

<h2>You should also read</h2>

<ul>

<li><a href="https://www.google.com/webmasters/tools/home?hl=en" class="external-link" target="_blank">Webmaster Tools</a></li>

<li><a href="https://support.google.com/webmasters/answer/183668" class="external-link" target="_blank">Creating Sitemaps</a></li>

<li><a href="https://support.google.com/webmasters/answer/182072?hl=en" class="external-link" target="_blank">Googlebot</a></li>

</ul>

</div>

</div>

<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 &lt;head&gt;} 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

href="https://docs.google.com/a/google.com/forms/d/1itcqPAQqggJ6e4m8aejWLM8Dc5O8P6qybgGbKCNxGV0/viewform"

class="external-link" target="_blank">App Indexing Expression of Interest</a> form.

</p>

<p>The deep links that you share with Google Search must take this URI

format:</p>

<pre>

android-app://<package_name>/<scheme>/<host_path>

</pre>

<p>The components that make up the URI format are:</p>

<ul>

<li><strong>package_name.</strong> Represents the package name for your APK as

listed in the <a href="https://play.google.com/apps/publish" class="external-link" target="_blank">Google Play Developer Console</a>.</li>

<li><strong>scheme.</strong> The URI scheme that matches your intent filter.</li>

<li><strong>host_path.</strong> Identifies the specific content within your application.

</li>

</ul>

<p>The following sections describe how to add a deep link URI to your Sitemap

or web pages.</p>

<h2 id="sitemap">Add Deep Links in Your Sitemap</h2>

<p>To annotate the deep link for Google Search app indexing in your

<a href="https://support.google.com/webmasters/answer/156184?hl=en" class="external-link" target="_blank">Sitemap</a>, use the

{@code &lt;xhtml:link&gt;} tag and specify the deep link as an alternate URI.</p>

<p>For example, the following XML snippet shows how you might specify a link to

your web page by using the {@code <loc>} tag, and a corresponding deep

link to your Android app by using the {@code &lt;xhtml:link&gt;} tag.</p>

<pre>

<?xml version="1.0" encoding="UTF-8" ?>

<urlset

    xmlns="http://www.sitemaps.org/schemas/sitemap/0.9"

    xmlns:xhtml="http://www.w3.org/1999/xhtml">

    <url>

        <loc>example://gizmos</loc>

            <xhtml:link

                rel="alternate"

                href="android-app://com.example.android/example/gizmos" />

    </url>

    ...

</urlset>

</pre>

<h2 id="webpages">Add Deep Links in Your Web Pages</h2>

<p>Instead of specifying the deep links for Google Search app indexing in your

Sitemap file, you can annotate the deep links in the HTML markup of your web

pages. You can do this in the {@code <head>} section for each web

page by adding a {@code <link>} tag and specifying the deep link as an

alternate URI.</p>

<p>For example, the following HTML snippet shows how you might specify the

corresponding deep link in a web page that has the URL

{@code example://gizmos}.</p>

<pre>

<html>

<head>

    <link rel="alternate"

          href="android-app://com.example.android/example/gizmos" />

    ...

</head>

<body> ... </body>

</pre>

<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

and Indexing Getting Started</a> guide.</p>

page.title=Making Your App Searchable

page.tags="app indexing"

trainingnavtop=true

startpage=true

@jd:body

<div id="tb-wrapper">

<div id="tb">

<h2>Dependencies and prerequisites</h2>

<ul>

  <li>Android 2.3 (API level 9) and higher</li>

</ul>

<h2>You Should Also Read</h2>

<ul>

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

<li><a href="https://developers.google.com/app-indexing/" class="external-link"

target="_blank">App Indexing for Google Search</a></li>

<li><a href="{@docRoot}guide/components/intents-filters.html">Intents and Intent

Filters</a></li>

</ul>

</div>

</div>

<a class="notice-developers-video wide" href="http://www.youtube.com/watch?v=Xh_W82JgOms">

<div>

    <h3>Video</h3>

    <p>DevBytes: App Indexing</p>

</div>

</a>

<p>As mobile apps become more pervasive, users are looking for relevant

information not only from web sites but also from apps they have installed.

You can enable Google to crawl through your app content and present your

Android app as a destination to users through Google Search results, when

that content corresponds to a web page that you own.</p>

<p>You can make it possible for Google Search to open specific content in your

  app by providing intent filters for your activities. Google Search

app indexing complements this capability by presenting links to relevant app

content alongside links to your web pages in users' search results. Users on

mobile devices can then click on a link to open your app from their search

results, allowing them to directly view your app's content instead of a

web page.</p>

<p>To enable Google Search app indexing, you need to provide Google with

information about the relationship between your app and web site. This process

involves the following steps:</p>

<ol>

<li>Enable deep linking to specific content

in your app by adding intent filters in your app manifest.</li>

<li>Annotate these links in the associated web pages on your web site or in a

	Sitemap file.</li>

<li>Opt in to allow Googlebot to crawl through your APK in the Google Play store

	to index your app content. You are automatically opted-in when you join as

	a participant in the early adopter program.

</li>

</ol>

<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

href="https://docs.google.com/a/google.com/forms/d/1itcqPAQqggJ6e4m8aejWLM8Dc5O8P6qybgGbKCNxGV0/viewform"

class="external-link" target="_blank">App Indexing Expression of Interest</a> form.

</p>

<p>This class shows how to enable deep linking and indexing of your application

content so that users can open this content directly from mobile search

results.</p>

<h2>Lessons</h2>

<!-- Create a list of the lessons in this class along with a short description of each lesson.

These should be short and to the point. It should be clear from reading the summary whether someone

will want to jump to a lesson or not.-->

<dl>

  <dt><b><a href="deep-linking.html">Enabling Deep Links for App

Content</a></b></dt>

    <dd>Shows how to add intent filters to enable deep linking to app

content.</dd>

  <dt><b><a href="enabling-app-indexing.html">Specifying  App Content for

Indexing</a></b></dt>

    <dd>Shows how to annotate web site metadata to allow Google's algorithms to index

app content.</dd>

</dl>

        </ul>

      </li>

     <li class="nav-section">

        <div class="nav-section-header">

          <a href="<?cs var:toroot ?>training/app-indexing/index.html"

             description=

             "How to enable deep linking and indexing of your application

content so that users can open this content directly from their mobile search

results."

            >Making Your App Content Searchable</a>

        </div>

        <ul>

          <li><a href="<?cs var:toroot ?>training/app-indexing/deep-linking.html">

            Enabling Deep Links for App Content

          </a>

          </li>

          <li><a href="<?cs var:toroot ?>training/app-indexing/enabling-app-indexing.html">

            Specifying  App Content for Indexing

          </a>

          </li>

        </ul>

      </li>

    </ul>

  </li>

  <!-- End best UX and UI -->