docs/html/design/wear/structure.jd

page.title=App Structure for Android Wear
@jd:body


<p>Users are used to tapping icons to launch apps. Android Wear is different. A typical Wear app adds a card to the stream at a contextually relevant moment. It might have a button that opens a full screen view for a fast micro interaction, like below, but it just as well might not.
</p>

<img src="{@docRoot}design/media/wear/appstructuresample.png" alt="" />

<p>These are the building blocks, ordered by simplicity. You can use one of them or some of them, but we strongly recommend not building apps the user has to launch and quit before thinking really hard about how you could react to a specific location, activity, time of day, or something happening in the cloud.</p>


<ul>
  <li><strong>Contextual card in the stream</strong>:
  <ul>
    <li><a href="#Bridged"><strong>Bridged notifications</strong></a> are pushed to the wearable from the connected handheld such as new message notifications, using standard Android notifications. These require little or no code on the wearable.
    <li><a href="#Contextual"><strong>Contextual notifications</strong></a> are generated locally on the wearable and appear at contextually relevant moments such as an exercise card that appears when you’re going on a run. You can do more with this kind of card than with a notification bridged from the handheld.
  </ul>
  </li>
  <li><strong>Full screen UI app</strong>:
  <ul>
    <li><a href="#2DPicker"><strong>2D Picker</strong></a> is design pattern that allows the user to select from a set of items, such as choosing artists and then albums. We recommend using this pre-built component from the SDK whenever relevant.
    <li><a href="#Custom"><strong>Custom layouts</strong></a> are also possible where apps need to extend beyond the basic card/stream metaphor.</li>
  </ul>
  </li>
</ul>

<p>Many applications will consist of a combination of these views, possibly with connections between them. For example, a contextual card may have an action that launches a more immersive experience. Inversely, an immersive experience may result in a card being added to the stream.</p>


<h2 id="Bridged">Bridged Notifications</h2>

<img src="{@docRoot}design/media/wear/bridgednotifications.jpg" height="147" style="float:right;margin:0 0 20px 20px" alt="">
<img src="{@docRoot}design/media/wear/Bluebird.png" height="147" style="float:right;margin:0 0 20px 40px" alt="">

<p>This is the simplest way to get on Android Wear. In fact, your app already does this if it uses notifications. You can add Wear-specific features like extra pages and voice replies by using the new notification APIs. </p>

<a class="notice-developers left" style="clear:none" href="{@docRoot}training/wearables/notifications/creating.html">
  <div>
    <h3>Developer Docs</h3>
    <p>Creating a Notification</p>
  </div>
</a>


<h2 id="Contextual" style="clear:both">Contextual Notifications</h2>


<img src="{@docRoot}design/media/wear/context_workout.png" width="323" height="147" style="float:right;margin:0 0 20px 40px;clear:right" alt="" />
<img src="{@docRoot}design/media/wear/context_lights.png" width="323" height="147" style="float:right;margin:0 0 20px 40px;clear:right" alt="" />

<p>This is what Android Wear does best; showing users information just when they need it.</p>

<p>Here’s how it works: Your app knows when it is relevant for the user, and when it happens, you trigger a contextual notification. Maybe you’re building a running app that’s relevant when the user is running. Maybe it’s a museum guide that’s relevant when the user is visiting a particular museum. Check out the design principles for more on thinking about your app contextually. </p>

<p>Getting contextual triggering right is one of the most impactful things you can do to craft a great user experience. </p>

<p>The easiest way to do this is to use standard templates for Android notifications. If you decide to make your own ActivityView, we strongly recommend you take a look at the <a href="{@docRoot}design/wear/style.html">Style</a> guide to make sure you stay consistent with the rest of the device. </p>

<p>Don’t forget to test your triggering thoroughly. Triggering too often can be so annoying that users might end up blocking all your notifications. </p>



<h2 id="2DPicker">2D Picker</h2>

<p>The 2D Picker design pattern (available as the <a href="{@docRoot}training/wearables/apps/layouts.html#UiLibrary">GridViewPager component</a>) is useful for showing a range of options or asking a user to make a quick selection. Google search results on Android Wear are a great example of the GridViewPager pattern in action.</p>

<img src="{@docRoot}design/media/wear/1D_picker.png" alt="" width="499px" />
<p class="img-caption">This pattern can be used to present a single vertical list, or a “1D Picker”</p>

<img src="{@docRoot}design/media/wear/2D_picker.png" alt="" width:760px" />
<p class="img-caption">It can also be used as a 2D matrix of options, as a way of presenting categorized options.</p>


<img src="{@docRoot}design/media/wear/2d_picker_indicated.png" alt="" width="760px" />
<p class="img-caption">Navigation should be vertical-then-horizontal, not horizontal-then-vertical, and limit the the vertical set to around five cards.</p>


<h3>Actions</h3>
<p>For actions on each cards, use the <a href="{@docRoot}design/wear/patterns.html#Actions">Action cards pattern</a>.</p>


<h3>Exiting</h3>
<p>2D Picker should be automatically dismissed when a selection is made. It may also be exited by swiping back down on the first card, or by swiping left to right on a leftmost card.</p>

<h3>Making it fast</h3>
<p>A few of our favorite tips on how to make the 2D picker really fast for your users:</p>
<ul>
<li>Minimize the number of cards</li>
<li>Show the most popular card at the top </li>
<li>Keep the cards extremely simple</li>
<li>Optimize for speed over customization</li>

</ul>



<h2 id="Custom">Breaking out of the card (with custom layouts)</h2>

<p>There are some things you can’t do on a card. Swiping in many directions on a map or a joystick are a few examples. In those cases it might be good idea to momentarily go full screen.</p>


<a class="notice-developers" href="{@docRoot}training/wearables/apps/index.html">
  <div>
    <h3>Developer Docs</h3>
    <p>Creating Wearable Apps</p>
  </div>
</a>

<img src="{@docRoot}design/media/wear/customlayout.png" alt="" width="760px" />

<h3>When to go full screen</h3>
<p>We highly recommend only going full screen when you can’t do what you want on a card, and quickly exit back to the stream the moment you’re done. That way your app will feel like an integrated part of the system.</p>

<h3>Be distinct</h3>
<p>Your full screen design shouldn’t look too much like the card stream or it could confuse users. The 2D picker is always available if you need a card-like UI.</p>

<h3>Automatically exiting</h3>
<p>Many devices don’t have back or home buttons, so exiting is your responsibility as the app designer. Here’s a few examples of natural exits:</p>
<ul>
  <li>A map that asks the user to drop a pin should exit when it happens</li>
  <li>A short game can exit when the game finishes</li>
  <li>A drawing app can finish after 5 seconds of inactivity.</li>
</ul>

<h3>Manually exiting</h3>
<p>Even with logical exit points like these, some cases may exist where the user may want to immediately exit. This may be common in apps that are used for a longer while. In all cases, the developer should present the option to quit the app on long press using 
<a href="{@docRoot}training/wearables/apps/layouts.html#UiLibrary"><code>DismissOverlayView</code></a>. Your design should reserve long press for the sole purpose of prompting to quit.</p>