diff options
21 files changed, 819 insertions, 130 deletions
diff --git a/docs/html/design/media/wear/ambient_list.png b/docs/html/design/media/wear/ambient_list.png Binary files differnew file mode 100644 index 000000000000..7425fb92c41d --- /dev/null +++ b/docs/html/design/media/wear/ambient_list.png diff --git a/docs/html/design/media/wear/ambient_list@2x.png b/docs/html/design/media/wear/ambient_list@2x.png Binary files differnew file mode 100644 index 000000000000..fe46575b5832 --- /dev/null +++ b/docs/html/design/media/wear/ambient_list@2x.png diff --git a/docs/html/design/media/wear/ambient_run.png b/docs/html/design/media/wear/ambient_run.png Binary files differnew file mode 100644 index 000000000000..7140f461d737 --- /dev/null +++ b/docs/html/design/media/wear/ambient_run.png diff --git a/docs/html/design/media/wear/ambient_run@2x.png b/docs/html/design/media/wear/ambient_run@2x.png Binary files differnew file mode 100644 index 000000000000..8ae41cc1406c --- /dev/null +++ b/docs/html/design/media/wear/ambient_run@2x.png diff --git a/docs/html/design/media/wear/interactive_list.png b/docs/html/design/media/wear/interactive_list.png Binary files differnew file mode 100644 index 000000000000..970d33a87c4b --- /dev/null +++ b/docs/html/design/media/wear/interactive_list.png diff --git a/docs/html/design/media/wear/interactive_list@2x.png b/docs/html/design/media/wear/interactive_list@2x.png Binary files differnew file mode 100644 index 000000000000..9d17456f31be --- /dev/null +++ b/docs/html/design/media/wear/interactive_list@2x.png diff --git a/docs/html/design/media/wear/interactive_run.png b/docs/html/design/media/wear/interactive_run.png Binary files differnew file mode 100644 index 000000000000..50b9a80e3874 --- /dev/null +++ b/docs/html/design/media/wear/interactive_run.png diff --git a/docs/html/design/media/wear/interactive_run@2x.png b/docs/html/design/media/wear/interactive_run@2x.png Binary files differnew file mode 100644 index 000000000000..5911367c54fc --- /dev/null +++ b/docs/html/design/media/wear/interactive_run@2x.png diff --git a/docs/html/design/wear/structure.jd b/docs/html/design/wear/structure.jd index 95d5c1aeecca..c1d9ef9dc925 100644 --- a/docs/html/design/wear/structure.jd +++ b/docs/html/design/wear/structure.jd @@ -22,14 +22,24 @@ margin: 0 10px 20px 20px; <ul> <li><strong>Contextual card in the stream</strong>: <ul> - <li><a href="#Bridged"><strong>Bridged notifications</strong></a>, such as new message notifications, are pushed to the wearable from the connected handheld using standard Android notifications. They require very little or no Wear-specific code. - <li><a href="#Contextual"><strong>Contextual notifications</strong></a>, such as an exercise card that appears when you begin running, are generated locally on the wearable and appear at contextually relevant moments. You can do more with this kind of card than with a notification bridged from the handheld. + <li><a href="#Bridged"><strong>Bridged notifications</strong></a>, such as new message + notifications, are pushed to the wearable from the connected handheld using standard Android + notifications. They require very little or no Wear-specific code.</li> + <li><a href="#Contextual"><strong>Contextual notifications</strong></a>, such as an exercise + card that appears when you begin running, are generated locally on the wearable and appear at + contextually relevant moments. You can do more with this kind of card than with a notification + bridged from the handheld.</li> </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 to select an artist then an album. 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, such as to present a graph or map.</li> + <li><a href="#2DPicker"><strong>2D Picker</strong></a> is a design pattern that allows the user + to select from a set of items, such as to select an artist then an album. We recommend using + this pre-built component from the SDK whenever relevant.</li> + <li><a href="#Custom"><strong>Custom layouts</strong></a> are also possible where apps need to + extend beyond the basic card/stream metaphor, such as to present a graph or map.</li> + <li><a href="#AlwaysOn"><strong>Keep your app always-on</strong></a> if you have information + that refreshes or stays relevant, without draining the battery.</li> </ul> </li> </ul> @@ -160,7 +170,77 @@ href="#2DPicker">2D picker</a> is always available.</p> <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, you should treat long-press as the user's intent to exit, using +<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, you +should treat long-press as the user's intent to exit, using <a href="{@docRoot}training/wearables/ui/exit.html"><code>DismissOverlayView</code></a>.</p> +<h2 id="AlwaysOn">Keeping the app always-on</h2> + +<a class="notice-developers" href="{@docRoot}training/wearables/apps/alwayson.html"> + <div> + <h3>Developer Docs</h3> + <p>Keeping Your App Always-On</p> + </div> +</a> + +<p>An Android Wear device has two modes:</p> + +<dl> +<dt><strong>Interactive mode</strong></dt> +<dd>A full-color mode where the user can interact with your app.</dd> +<dt><strong>Ambient mode</strong></dt> +<dd>A low-power mode where the screen is rendered in black and white, with +minimal grayscale graphics.</dd> +</dl> + +<p>Interactive activities provide real-time information and feedback to the user, but it can quickly +drain the device's battery. To reduce battery usage and still present useful information, apps can +transition into an ambient mode called <i>always-on</i>. +</p> + +<p>Your app can display dynamic data on the device, even when the app is in ambient mode. This +approach is useful if your app displays information that is continuously updated, like a running +tracker app, or when it presents information the user needs for reference, like a grocery app.</p> + +<p>Typical user experiences with apps that switch into ambient mode on Android Wear look like +this:</p> + +<img src="{@docRoot}design/media/wear/interactive_run.png" height="147" width="147" + srcset="{@docRoot}design/media/wear/interactive_run@2x.png 2x" style="float:left;margin:0 0 20px 40px" alt=""> +<img src="{@docRoot}design/media/wear/ambient_run.png" height="147" width="147" + srcset="{@docRoot}design/media/wear/ambient_run@2x.png 2x" style="float:left;margin:0 0 20px 40px" alt=""> +<img src="{@docRoot}design/media/wear/interactive_list.png" height="147" width="147" + srcset="{@docRoot}design/media/wear/interactive_list@2x.png 2x" style="float:left;margin:0 0 20px 40px" alt=""> +<img src="{@docRoot}design/media/wear/ambient_list.png" height="147" width="147" + srcset="{@docRoot}design/media/wear/ambient_list@2x.png 2x" style="float:left;margin:0 0 20px 40px" alt=""> +<p class="img-caption">When the app switches to ambient mode, remove all elements that invite +touch or indicate the elements are disabled. In addition, consider showing the current time.</p> + +<h3>Update frequency</h3> + +<p>You should only update the display once per minute, to preserve battery life of the wearable +device. You can update the display every 10 seconds, but make sure you only update when absolutely +necessary. Every update depletes the device's battery. +</p> + +<h3>Interactive elements</h3> + +<p>Don’t present any buttons or other interactive elements when the app is in ambient mode. This +approach could mislead the user into thinking the app is in interactive mode.</p> + +<h3>Colors and brightness</h3> + +<p>Use grayscale colors to help signal that the user must wake up the device before they can +interact with it. Also note that any pixel that is not black will be noticeably bright for users in +dimly lit rooms. We strongly recommend keeping the background black whenever possible.</p> + +<h3>Privacy</h3> + +<p>Consider the user’s privacy when designing and developing an app that displays data in ambient +mode. For example, while keeping a messaging app on the screen could be convenient for a user who is +in an ongoing conversation, displaying personal messages on the screen for an extended period of +time while the app is in ambient mode may bother some users. Consider removing potentially private +data after a short period of inactivity or refrain from showing sensitive data in ambient mode. +</p> diff --git a/docs/html/google/play/billing/billing_reference.jd b/docs/html/google/play/billing/billing_reference.jd index 01e680fd54b6..7884929e44e8 100644 --- a/docs/html/google/play/billing/billing_reference.jd +++ b/docs/html/google/play/billing/billing_reference.jd @@ -172,8 +172,8 @@ does not include tax.</td> </tr> <tr> <td>{@code INAPP_DATA_SIGNATURE}</td> - <td>String containing the signature of the purchase data that was signed -with the private key of the developer. The data signature uses the + <td>String containing the signature of the purchase data that was signed +with the private key of the developer. The data signature uses the RSASSA-PKCS1-v1_5 scheme.</td> </tr> </table> @@ -197,7 +197,13 @@ RSASSA-PKCS1-v1_5 scheme.</td> lose access at that time unless they re-enable automatic renewal (or manually renew, as described in <a href="{@docRoot}google/play/billing/billing_subscriptions.html#manual-renewal">Manual - Renewal</a>).</td> + Renewal</a>). + If you offer a <a href="{@docRoot}google/play/billing/billing_subscriptions.html#grace-period" + >grace period</a>, this value remains set to <code>true</code> for all + subscriptions, as long as the grace period has not lapsed. The next billing date + is extended dynamically every day until the end of the grace period or until the + user fixes their payment method. + </td> </tr> <tr> <td>{@code orderId}</td> diff --git a/docs/html/google/play/billing/billing_subscriptions.jd b/docs/html/google/play/billing/billing_subscriptions.jd index 8f55354e5b6d..f7df7524e8c1 100644 --- a/docs/html/google/play/billing/billing_subscriptions.jd +++ b/docs/html/google/play/billing/billing_subscriptions.jd @@ -47,42 +47,42 @@ meta.tags="monetization, inappbilling, subscriptions" </div> <p>Subscriptions let you sell content, services, or features in your app with -automated, recurring billing. You can easily adapt an existing In-app Billing +automated, recurring billing. You can easily adapt an existing In-app Billing implementation to sell subscriptions.</p> -<p>This document is focused on highlighting implementation details that are -specific to subscriptions, along with some strategies for the associated billing +<p>This document is focused on highlighting implementation details that are +specific to subscriptions, along with some strategies for the associated billing and business models.</p> <h2 id="overview">Overview of Subscriptions</h2> -<p>A <em>subscription</em> is a product type offered in In-app Billing that -lets you sell content, services, or features to users from inside your app with +<p>A <em>subscription</em> is a product type offered in In-app Billing that +lets you sell content, services, or features to users from inside your app with recurring, automated billing at the interval you specify. You can sell subscriptions to almost any type of digital content, from any type of app or game.</p> <p>As with other in-app products, you configure and publish subscriptions using -the Developer Console and then sell them from inside apps installed on +the Developer Console and then sell them from inside apps installed on Android devices. In the Developer console, you create subscription products and add them to a product list, then set a price and optional trial period for each, choose a billing interval, and then -publish. For more information about using the Developer Console, see +publish. For more information about using the Developer Console, see <a href="#administering">Configuring Subscription Items</a>.</p> -<p>When users purchase subscriptions in your apps, Google Play handles all -checkout details so your apps never have to directly process any financial -transactions. Google Play processes all payments for subscriptions through -Google Wallet, just as it does for standard in-app products and app purchases. +<p>When users purchase subscriptions in your apps, Google Play handles all +checkout details so your apps never have to directly process any financial +transactions. Google Play processes all payments for subscriptions through +Google Wallet, just as it does for standard in-app products and app purchases. This ensures a consistent and familiar purchase flow for your users.</p> <img src="{@docRoot}images/in-app-billing/v3/billing_subscription_v3.png" style="float:right; border:4px solid ddd;"> -<p>After users have purchased subscriptions, they can view the subscriptions and -cancel them from the <strong>My Apps</strong> screen in the Play Store app or -from the app's product details page in the Play Store app. For more information +<p>After users have purchased subscriptions, they can view the subscriptions and +cancel them from the <strong>My Apps</strong> screen in the Play Store app or +from the app's product details page in the Play Store app. For more information about handling user cancellations, see <a href="#cancellation">Subscription Cancellation</a>.</p> -<p>In addition to client-side API calls, you can use the server-side API for -In-app Billing to provide subscription purchasers with extended access to +<p>In addition to client-side API calls, you can use the server-side API for +In-app Billing to provide subscription purchasers with extended access to content (for example, from your web site or another service). The server-side API lets you validate the status of a subscription when users sign into your other services. For more information about the API, see <a @@ -95,12 +95,12 @@ Android apps.</p> your own business logic to your Android app to determine whether the user has already purchased a subscription elsewhere, then allow access to your content if so or offer a subscription purchase from Google Play if not.</li> -<li>You can implement your own solution for sharing subscriptions across as -many different apps or products as you want. For example, you could sell a -subscription that gives a subscriber access to an entire collection of apps, -games, or other content for a monthly or annual fee. To implement this solution, -you could add your own business logic to your app to determine whether the user -has already purchased a given subscription and if so, allow access to your +<li>You can implement your own solution for sharing subscriptions across as +many different apps or products as you want. For example, you could sell a +subscription that gives a subscriber access to an entire collection of apps, +games, or other content for a monthly or annual fee. To implement this solution, +you could add your own business logic to your app to determine whether the user +has already purchased a given subscription and if so, allow access to your content.</li> </ul> </p> @@ -111,14 +111,14 @@ information about the current policies and terms, please read the <a href="http://support.google.com/googleplay/android-developer/bin/answer.py?hl=en &answer=140504">policies document</a>.</p> -<p>To learn about the minimum system requirements for +<p>To learn about the minimum system requirements for subscriptions, see the <a href="{@docRoot}google/play/billing/versions.html#Subs">Version Notes</a>.</p> <h2 id="administering">Configuring Subscription Items</h2> <p>To create and manage subscriptions, you can use the Developer Console to set up a -product list for the app, then configure these attributes for each subscription +product list for the app, then configure these attributes for each subscription product:</p> <ul> @@ -133,7 +133,7 @@ product:</p> <li>Additional currency pricing (can be auto-filled)</li> </ul> -<p>For details on how to add and configure products in the Developer Console, +<p>For details on how to add and configure products in the Developer Console, see <a href="{@docRoot}google/play/billing/billing_admin.html">Administering In-app Billing</a>.</p> @@ -149,18 +149,20 @@ price. You can price multiple subscriptions for the same content differently — for example you could offer a discount on an annual subscription relative to the monthly equivalent. </p> -<p class="caution"><strong>Important</strong>: To change the price of a -subscription, you can publish a new subscription product ID at a new price, -then offer it in your app instead of the original product. Users who have -already purchased will continue to be charged at the +<p class="caution"><strong>Important</strong>: To change the price of a +subscription, you can publish a new subscription product ID at a new price, +then offer it in your app instead of the original product. Users who have +already purchased will continue to be charged at the original price, but new users will be charged at the new price.</p> <h3 id="user-billing">User billing</h3> -<p>In the Developer Console, you can configure subscription products with +<p>In the Developer Console, you can configure subscription products with automated recurring billing at your choice of intervals:</p> <ul> + <li>Weekly — Google Play bills the customer’s Google Wallet account at + the time of purchase and every week after the original purchase date.</li> <li>Monthly — Google Play bills the customer’s Google Wallet account at the time of purchase and monthly subsequent to the purchase date (exact billing intervals can vary slightly over time).</li> @@ -183,32 +185,27 @@ monthly and annual subscriptions, billing cycles will always match subscription cycles, based on the purchase date. (Seasonal subscriptions are charged annually, on the first day of the season.)</p> -<p>Over the life of a subscription, the form of payment billed remains the same -— Google Play always bills the same form of payment (such as credit card -or by Direct Carrier Billing) that was originally used to purchase the -subscription.</p> - -<p>When the subscription payment is approved by Google Wallet, Google Play +<p>When the subscription payment is approved, Google Play provides a purchase token back to the purchasing app through the In-app Billing -API. Your apps can store the token locally or pass it to your backend servers, +API. Your apps can store the token locally or pass it to your backend servers, which can then use it to validate or cancel the subscription remotely using the <a href="{@docRoot}google/play/billing/gp-purchase-status-api.html">Google Play Developer API</a>.</p> <p>If a recurring payment fails (for example, because the customer’s credit -card has become invalid), the subscription does not renew. How your app is +card has become invalid), the subscription does not renew. How your app is notified depends on the In-app Billing API version that you are using:</p> <ul> -<li>With In-app Billing Version 3, the failed or expired subscription is no longer +<li>With In-app Billing Version 3, the failed or expired subscription is no longer returned when you call {@code getPurchases}.</li> -<li>With In-app Billing Version 2, Google Play notifies your app at the end of -the active cycle that the purchase state of the subscription is now "Expired". +<li>With In-app Billing Version 2, Google Play notifies your app at the end of +the active cycle that the purchase state of the subscription is now "Expired". </li> </ul> -<p class="note"><strong>Recommendation</strong>: Include business logic in your -app to notify your backend servers of subscription purchases, tokens, and any -billing errors that may occur. Your backend servers can use the server-side API +<p class="note"><strong>Recommendation</strong>: Include business logic in your +app to notify your backend servers of subscription purchases, tokens, and any +billing errors that may occur. Your backend servers can use the server-side API to query and update your records and follow up with customers directly, if needed.</p> <h3 id="manual-renewal">Manual Renewal</h3> @@ -220,8 +217,8 @@ is active, it is extended by the appropriate period at the current rate.</p> <p>For example, Achilles has a subscription to the <em>Modern Hoplite</em> app. His subscription is currently due to expire on August 1. On July 10, he -purchases a 3-month subscription at the current rate. Those three months are -added to his existing subscription, so the subscription now expires on November +purchases a 1-month subscription at the current rate. This one month is +added to his existing subscription, so the subscription now expires on September 1.</p> <p>It is up to the app to convey this with an appropriate UI. For example, if a @@ -311,9 +308,9 @@ date to 15 August 2015 14:00:00 UTC.</p> <h3 id="trials">Free trials</h3> <p>In the Developer Console, you can set up a free trial period that lets users -try your subscription content before buying it. The trial period runs for the -period of time that you set and then automatically converts to a full -subscription managed according to the subscription's billing interval and +try your subscription content before buying it. The trial period runs for the +period of time that you set and then automatically converts to a full +subscription managed according to the subscription's billing interval and price. Free trials are supported for monthly and annual subscriptions only, and are not supported for seasonal subscriptions.</p> <p>To take advantage of a free trial, a user must "purchase" the full @@ -328,7 +325,7 @@ by email that they have purchased a subscription that includes a free trial period and that the initial charge was $0.00. </p> <p>When the trial period ends, Google Play automatically initiates billing -against the credit card that the user provided during the initial purchase, at +against the credit card that the user provided during the initial purchase, at the amount set for the full subscription, and continuing at the subscription interval. If necessary, the user can cancel the subscription at any time during the trial @@ -367,15 +364,15 @@ publish the product before Google Play can make it available for purchase. Note that you must also publish the app itself before Google Play will make the products available for purchase inside the app. </p> -<p class="caution"><strong>Important</strong>: You can remove the subscription -product from the product list offered in your app to prevent users from seeing +<p class="caution"><strong>Important</strong>: You can remove the subscription +product from the product list offered in your app to prevent users from seeing or purchasing it.</p> <h2 id="cancellation">Subscription Cancellation</h2> <p>Users can view the status of all of their subscriptions and cancel them if -necessary from the <strong>My Apps</strong> screen in the Play Store app. -Currently, the In-app Billing API does not provide support for programatically +necessary from the <strong>My Apps</strong> screen in the Play Store app. +Currently, the In-app Billing API does not provide support for programatically canceling subscriptions from inside the purchasing app.</p> <p>When the user cancels a subscription, Google Play does not offer a refund for @@ -404,12 +401,12 @@ href="http://support.google.com/googleplay/android-developer/bin/answer.py?hl=en <h3 id="uninstall">App uninstallation</h3> -<p>When the user uninstalls an app that includes purchased subscriptions, the -Play Store app will notify the user that there are active subscriptions. If the -user chooses to continue with the uninstallation, the app is removed and the -subscriptions remain active and recurring billing continues. The user can return -to cancel the associated subscriptions at any time in the <strong>My Apps</strong> -screen of the Play Store app. If the user chooses to cancel the uninstallation, +<p>When the user uninstalls an app that includes purchased subscriptions, the +Play Store app will notify the user that there are active subscriptions. If the +user chooses to continue with the uninstallation, the app is removed and the +subscriptions remain active and recurring billing continues. The user can return +to cancel the associated subscriptions at any time in the <strong>My Apps</strong> +screen of the Play Store app. If the user chooses to cancel the uninstallation, the app and subscriptions remain as they were.</p> <h3 id="refunds">Refunding and revoking subscriptions</h3> @@ -436,8 +433,8 @@ at this time.</p> <h2 id="payment">Payment Processing and Policies</h2> <p>In general, the terms of Google Play allow you to sell in-app subscriptions -only through the standard payment processor, Google Wallet. For purchases of -any subscription products, the transaction fee is the same as the transaction +only through the standard payment processor, Google Wallet. For purchases of +any subscription products, the transaction fee is the same as the transaction fee for application purchases (30%).</p> <p>Apps published on Google Play that are selling subscriptions must use In-app @@ -451,7 +448,7 @@ document</a>.</p> <h3 id="orderId">Subscription order numbers</h3> <p>To help you track transactions relating to a given subscription, Google -Wallet provides a base Merchant Order Number for all recurrences of the +Wallet provides a base Merchant Order Number for all recurrences of the subscription and denotes each recurring transaction by appending an integer as follows: </p> @@ -461,10 +458,29 @@ each recurring transaction by appending an integer as follows: </p> <code>12999556515565155651.5565135565155651..2</code> (third recurrence orderID)<br /> ...<br /></p> -<p>Google Play provides the order number as the value of the -{@code orderId} field of the {@code INAPP_PURCHASE_DATA} JSON field (in V3) +<p>Google Play provides the order number as the value of the +{@code orderId} field of the {@code INAPP_PURCHASE_DATA} JSON field (in V3) or the {@code PURCHASE_STATE_CHANGED} intent (in V2).</p> +<h3 id="grace-period">Grace period for declined payments</h3> + +<p> + The Developer Console allows you to set a grace period for subscriptions, so you can give + your subscribers a chance to update their payment method if a recurring payment is declined. + This setting is useful if your subscribers have an expired credit card, subscribed using a + prepaid card, or canceled a card without updating their payment information. For + information about setting a grace period for subscriptions, see the Developer Console Help + topic <a href="https://support.google.com/googleplay/android-developer/answer/140504" + class="external-link">Add subscriptions & recurring charges</a>. +</p> + +</p> + For information on how setting a grace period affects data returned from the + {@code getBuyIntent()} method, see the + <a href="{@docRoot}google/play/billing/billing_reference.html#purchase-data-table" + >{@code INAPP_PURCHASE_DATA}</a> fields table. +</p> + <h2 id="strategies">Purchase Verification Strategies</h2> <p>In a typical scenario, your app verifies the order status for new purchases diff --git a/docs/html/google/play/billing/index.jd b/docs/html/google/play/billing/index.jd index 47620c80aaa1..c671c71fc859 100644 --- a/docs/html/google/play/billing/index.jd +++ b/docs/html/google/play/billing/index.jd @@ -7,7 +7,7 @@ page.tags="billing, inapp, iap" <p>In-app Billing is a Google Play service that lets you sell digital content from inside your applications. You can use the service to sell a wide range of content, including downloadable -content such as media files or photos, virtual content such as game levels or potions, premium services +content such as media files or photos, virtual content such as game levels or potions, premium services and features, and more. You can use In-app Billing to sell products as</p> <div class="sidebox-wrapper"> @@ -34,17 +34,14 @@ and features, and more. You can use In-app Billing to sell products as</p> <a href="billing_subscriptions.html#deferred-billing">defer</a> a subscriber's next billing date until the date you choose. The user still has access to the content but is not charged during the deferral period.</li> - <li><strong>Google Play Developer API</strong>—The - <a href="{@docRoot}google/play/billing/gp-purchase-status-api.html">Google - Play Developer API</a> allows you to perform a number of publishing and - app-management tasks. It includes the functionality previously known as the - <em>Purchase Status API.</em> </li> - <li><strong>Refund/Revoke subscription</strong>—You can use the - Google Play Developer API to <a href="billing_subscriptions.html#refunds">refund - and revoke</a> a user's subscription. If you do this, the user's - subscription ends - immediately, and his or her most recent subscription payment is - refunded.</li> + <li><strong>Weekly subscriptions</strong>—You can now set up a + recurring <a href="billing_subscriptions.html#user-billing">subscription</a> + that bills the user every week.</li> + <li><strong>Payment grace period</strong>—If a subscriber misses a + subscription payment due to an expired credit card, you can define a + <a href="billing_subscriptions.html#grace-period">grace period</a> + to the continue the subscription until payment is successful.</li> + </ul> </div> </div> @@ -69,7 +66,7 @@ Wallet merchant account.</p> provides a sample application that demonstrates how to sell standard in-app products and subscriptions from inside an app.</p> -<p>To get started, read the documents below or take the <a href="{@docRoot}training/in-app-billing/index.html">Selling +<p>To get started, read the documents below or take the <a href="{@docRoot}training/in-app-billing/index.html">Selling In-app Products</a> training class.</p> <dl> diff --git a/docs/html/tools/building/building-cmdline.jd b/docs/html/tools/building/building-cmdline.jd index 33798a521821..0e4c8b2631e1 100644 --- a/docs/html/tools/building/building-cmdline.jd +++ b/docs/html/tools/building/building-cmdline.jd @@ -43,7 +43,7 @@ parent.link=index.html <p>Whether you're building with the debug or release build type, you need to run and build your module. This will create the .apk file that you can install on an emulator or device. When you build using the debug build type, the .apk file is automatically signed by the SDK tools - with a debug key based on the <code>debuggable true</code> setting in the module's gradle.build file, + with a debug key based on the <code>debuggable true</code> setting in the module's build.gradle file, so it's instantly ready for installation onto an emulator or attached development device. You cannot distribute an application that is signed with a debug key. When you build using the release build type, the .apk file is <em>unsigned</em>, so you @@ -174,7 +174,7 @@ $ ./gradlew assembleRelease the build will prompt you for your keystore and alias password when you build using the release build type and produce your final application package, which will be ready for distribution.</p> - <p>To specify your keystore and alias, open the module gradle.build file (found in + <p>To specify your keystore and alias, open the module build.gradle file (found in the root of the module directory) and add entries for {@code storeFile}, {@code storePassword}, {@code keyAlias} and {@code keyPassword}. For example:</p> @@ -188,7 +188,7 @@ keyAlias "MyReleaseKey" <ol> <li>Open a command-line and navigate to the root of your module directory.</li> - <li>Edit the gradle.build file to build your project in release mode: + <li>Edit the build.gradle file to build your project in release mode: <p><pre> ... android { @@ -222,7 +222,7 @@ android { <p>This creates your Android application .apk file inside the module <code>build/</code> directory, named <code><em><your_module_name></em>-release.apk</code>. This .apk file has - been signed with the private key specified in gradle.build file and aligned with {@code + been signed with the private key specified in build.gradle file and aligned with {@code zipalign}. It's ready for installation and distribution.</p> <h3 id="OnceBuilt">Once built and signed in release mode</h3> diff --git a/docs/html/tools/devices/index.jd b/docs/html/tools/devices/index.jd index 1ea4c478b8b2..6263c8b5a6b6 100644 --- a/docs/html/tools/devices/index.jd +++ b/docs/html/tools/devices/index.jd @@ -5,16 +5,16 @@ page.title=Managing Virtual Devices <p>An Android Virtual Device (AVD) is an emulator configuration that lets you model an actual device by defining hardware and software options to be emulated by the Android Emulator.</p> - <p>The easiest way to create an AVD is to use the graphical <a href= - "{@docRoot}tools/devices/managing-avds.html">AVD Manager</a>, which you launch - from Eclipse by clicking <strong>Window > AVD Manager</strong>. You can also start the AVD -Manager from the command line by calling the <code>android</code> tool with the <code>avd</code> -options, from the <strong><sdk>/tools/</strong> directory.</p> + <p>The easiest way to create an AVD is to use the graphical + <a href="{@docRoot}tools/devices/managing-avds.html">AVD Manager</a>, which you launch + from Android Studio by clicking <strong>Tools > Android > AVD Manager</strong>. You can + also start the AVD Manager from the command line by calling the <code>android</code> tool with + the <code>avd</code> options, from the <strong><sdk>/tools/</strong> directory.</p> <p>You can also create AVDs on the command line by passing the <code>android</code> tool options. - For more information on how to create AVDs in this manner, see <a href= - "{@docRoot}tools/devices/managing-avds-cmdline.html">Managing Virtual - Devices from the Command Line</a>.</p> + For more information on how to create AVDs in this manner, see + <a href="{@docRoot}tools/devices/managing-avds-cmdline.html">Managing Virtual Devices from the + Command Line</a>.</p> <p>An AVD consists of:</p> diff --git a/docs/html/tools/devices/managing-avds-cmdline.jd b/docs/html/tools/devices/managing-avds-cmdline.jd index ba353c1538da..c16b1f85e6a2 100644 --- a/docs/html/tools/devices/managing-avds-cmdline.jd +++ b/docs/html/tools/devices/managing-avds-cmdline.jd @@ -84,8 +84,8 @@ id: 5 or "android-9" <h2 id="AVDCmdLine">Creating AVDs</h2> -<p>In addition to creating AVDs with the -<a href="{@docRoot}tools/devices/managing-avds-cmdline.html">AVD Manager user interface</a>, +<p>In addition to creating AVDs with the +<a href="{@docRoot}tools/help/avd-manager.html">AVD Manager user interface</a>, you can also create them by passing in command line arguments to the <code>android</code> tool. </p> diff --git a/docs/html/tools/sdk/ndk/index.jd b/docs/html/tools/sdk/ndk/index.jd index 520fe670bd5d..ae15bc14c377 100644 --- a/docs/html/tools/sdk/ndk/index.jd +++ b/docs/html/tools/sdk/ndk/index.jd @@ -2,29 +2,25 @@ ndk=true page.template=sdk -ndk.mac64_download=android-ndk-r10d-darwin-x86_64.bin -ndk.mac64_bytes=442691567 -ndk.mac64_checksum=cb101e1e62d56ea75b215f6bc6c27fae +ndk.mac64_download=android-ndk-r10e-darwin-x86_64.bin +ndk.mac64_bytes=388937326 +ndk.mac64_checksum=2cb8893a5701603519d38a7e04c50e81 -ndk.mac32_download=android-ndk-r10d-darwin-x86.bin -ndk.mac32_bytes=441545213 -ndk.mac32_checksum=0aeb3dc062dc457a4cd01e72eadb2379 +ndk.linux64_download=android-ndk-r10e-linux-x86_64.bin +ndk.linux64_bytes=401522849 +ndk.linux64_checksum=19af543b068bdb7f27787c2bc69aba7f -ndk.linux64_download=android-ndk-r10d-linux-x86_64.bin -ndk.linux64_bytes=459151600 -ndk.linux64_checksum=263b83071e6bca15f67898548d8d236e +ndk.linux32_download=android-ndk-r10e-linux-x86.bin +ndk.linux32_bytes=394281908 +ndk.linux32_checksum=c3edd3273029da1cbd2f62c48249e978 -ndk.linux32_download=android-ndk-r10d-linux-x86.bin -ndk.linux32_bytes=449997190 -ndk.linux32_checksum=70ed6d8c34e7e620c145b791e8eeef89 +ndk.win64_download=android-ndk-r10e-windows-x86_64.exe +ndk.win64_bytes=419616132 +ndk.win64_checksum=8412bb4991a95e08fda50b5a44d95df7 -ndk.win64_download=android-ndk-r10d-windows-x86_64.exe -ndk.win64_bytes=472613732 -ndk.win64_checksum=9a33f96da58a7e0b70e47d27b4a880b4 - -ndk.win32_download=android-ndk-r10d-windows-x86.exe -ndk.win32_bytes=455427281 -ndk.win32_checksum=c0930abfae0c990c4d191cc4ebd46b68 +ndk.win32_download=android-ndk-r10e-windows-x86.exe +ndk.win32_bytes=396563176 +ndk.win32_checksum=1a82445baaf62aec3a46386ab1e5772c @@ -382,11 +378,174 @@ $('#Downloads').after($('#download-table')); <p>The following sections provide information about releases of the NDK.</p> - <div class="toggle-content opened"> <p> <a href="#" onclick="return toggleContent(this)"> <img src="/assets/images/triangle-opened.png" class="toggle-content-img" alt="" + >Android NDK, Revision 10e</a> <em>(May 2015)</em> + </p> + <div class="toggle-content-toggleme"> + <dl> + <dt>Important changes:</dt> + <dd> + <ul> + <li>Integrated the workaround for Cortex-A53 Erratum 843419 into the + {@code aarch64-linux-android-4.9} linker. For more information on this workaround, see + <a href="https://sourceware.org/ml/binutils/2015-03/msg00446.html">Workaround for cortex-a53 + erratum 843419.</a></li> + + <li>Added Clang 3.6; {@code NDK_TOOLCHAIN_VERSION=clang} now picks that version + of Clang by default.</li> + + <li>Removed Clang 3.4.</li> + + <li>Removed GCC 4.6.</li> + + <li>Implemented multithreading support in {@code ld.gold} for all architectures. It can + now link with or without support for multithreading; the default is to do it without. + <ul> + <li>To compile with multithreading, use the {@code --threads} option.</li> + <li>To compile without multithreading, use the {@code --no-threads} option.</li> + </ul> + </li> + + <li>Upgraded GDB/gdbserver to 7.7 for all architectures.</li> + + <li>Removed the NDK package for 32-bit Darwin.</li> + </ul> + </dd> + <dl> + + + <dt>Important bug fixes:</dt> + <dd> + <ul> + <li>Fixed a crash that occurred when there were OpenMP loops outside of the main thread.</li> + + <li>Fixed a GCC 4.9 internal compiler error (<i>ICE</i>) that occured when the user declared + {@code #pragma GCC optimize ("O0")}, but had a different level of optimization specified + on the command line. The {@code pragma} takes precedence.</li> + + <li>Fixed an error that used to produce a crash with the following error message: +<pre> +in add_stores, at var-tracking.c:6000 +</pre> + </li> + + <li>Implemented a workaround for a Clang 3.5 issue in which LLVM auto-vectorization + generates {@code llvm.cttz.v2i64()}, an instruction with no counterpart in the ARM + instruction set.</li> + </ul> + </dd> + + <dt>Other bug fixes:</dt> + <dd> + <ul> + <li>Made the following header and library fixes:</li> + <ul> + <li>Fixed {@code PROPERTY_*} in {@code media/NdkMediaDrm.h}.</li> + <li>Fixed {@code sys/ucontext.h} for {@code mips64}.</li> + <li>Dropped the Clang version check for {@code __builtin_isnan} and + {@code __builtin_isinf}.</li> + <li>Added {@code android-21/arch-mips/usr/include/asm/reg.h} + and {@code android-21/arch-mips64/usr/include/asm/reg.h}.</li> + </ul> + </li> + + <li>Fixed a spurious array-bounds warning that GCC 4.9 produced for x86, and reenabled the + array bounds warning that GCC 4.9 had produced for ARM. The warning for ARM had + previously been unconditionally disabled.</li> + + <li>Fixed Clang 3.5 for {@code mips} and {@code mips64} to create a writable + {@code .gcc_except_table} section, thus matching GCC behavior. This change allows you + to avoid the following linker warning: + +<pre> +.../ld: warning: creating a DT_TEXTREL in a shared object +</pre> + </li> + + <li>Backported a fix for {@code compiler-rt} issues that were causing crashes when Clang + compiled for {@code mips64}. For more information, see LLVM Issue + <a href="http://llvm.org/bugs/show_bug.cgi?id=20098">20098</a>.</li> + + <li>Fixed Clang 3.5 crashes that occurred on non-ASCII comments. (Issue + <a href="https://code.google.com/p/android/issues/detail?id=81440">81440</a>)</li> + + <li>Fixed {@code stlport collate::compare} to return {@code -1} and {@code 1}. Previously, + it had returned arbitrary signed numbers.</li> + + <li>Fixed {@code ndk-gdb} for 64-bit ABIs. (Issue + <a href="https://code.google.com/p/android/issues/detail?id=118300">118300</a>)</li> + + <li>Fixed the crash that the HelloComputeNDK sample for RenderScript was producing on + Android 4.4 (Android API level 19). For more information, see + <a href="http://stackoverflow.com/questions/28057049/targeting-pre-lollipop-devices-using-renderscript-from-ndk-c">this page</a>.</li> + + <li>Fixed {@code libc++ __wrap_iter} for GCC. For more information, see LLVM Issue + <a href="http://llvm.org/bugs/show_bug.cgi?id=22355">22355</a>.</li> + + <li>Fixed {@code .asm} support for ABI {@code x86_64}.</li> + + <li>Implemented a workaround for the GCC 4.8 {@code stlport} issue. (Issue + <a href="https://android-review.googlesource.com/#/c/127773">127773</a>)</li> + + <li>Removed the trailing directory separator {@code \\} from the project path in Windows. + (Issue <a href="https://code.google.com/p/android/issues/detail?id=160584">160584</a>) + </li> + + <li>Fixed a {@code no rule to make target} error that occurred when compiling a single + {@code .c} file by executing the {@code ndk-build.cmd} command from {@code gradle}. (Issue + <a href="https://code.google.com/p/android/issues/detail?id=66937">66937</a>)</li> + + <li>Added the {@code libatomic.a} and {@code libgomp.a} libraries that had been missing from + the following host toolchains: + <ul> + <li>{@code aarch64-linux-android-4.9}</li> + <li>{@code mips64el-linux-android-4.9}</li> + <li>{@code mipsel-linux-android-4.9}</li> + <li>{@code x86_64-4.9}</li> + </ul> + </ul> + </dd> + + <dt>Other changes:</dt> + <dd> + <ul> + <li>Added {@code ld.gold} for {@code aarch64}. The default linker remains {@code ld.bfd}. + To explicitly enable {@code ld.gold}, add {@code -fuse-ld=gold} to the + {@code LOCAL_LDFLAGS} or {@code APP_LDFLAGS} variable.</li> + + <li>Built the MIPS and MIPS64 toolchains with {@code binutils-2.25}, which provides improved + R6 support.</li> + + <li>Made {@code -fstandalone-debug} (full debug info) a default option for Clang.</li> + + <li>Replaced {@code -fstack-protector} with {@code -fstack-protector-strong} for + the ARM, AArch64, X86, and X86_64 toolchains for GCC 4.9, Clang 3.5, and + Clang 3.6.</li> + + <li>Added the {@code --package} command-line switch to {@code ndk-gdb} to allow the build + system to override the package name. (Issue + <a href="https://code.google.com/p/android/issues/detail?id=56189">56189</a>)</li> + + <li> Deprecated {@code -mno-ldc1-stc1} for MIPS. This option may not work with the new + {@code -fpxx} and {@code -mno-odd-spreg} options, or with the FPXX ABI.</li> + + <li>Added MIPS MSA and R6 detection to {@code cpu-features}.</li> + + </ul> + </dd> + + </dl> + </div> +</div> + + +<div class="toggle-content closed"> + <p> + <a href="#" onclick="return toggleContent(this)"> <img + src="/assets/images/triangle-closed.png" class="toggle-content-img" alt="" >Android NDK, Revision 10d</a> <em>(December 2014)</em> </p> <div class="toggle-content-toggleme"> diff --git a/docs/html/training/training_toc.cs b/docs/html/training/training_toc.cs index 089739bd002f..82d0a90c1de7 100644 --- a/docs/html/training/training_toc.cs +++ b/docs/html/training/training_toc.cs @@ -792,6 +792,9 @@ include the action bar on devices running Android 2.1 or higher." <a href="<?cs var:toroot ?>training/wearables/apps/layouts.html">Creating Custom Layouts</a> </li> <li> + <a href="<?cs var:toroot ?>training/wearables/apps/always-on.html">Keeping Your App Visible</a> + </li> + <li> <a href="<?cs var:toroot ?>training/wearables/apps/voice.html">Adding Voice Capabilities</a> </li> <li> diff --git a/docs/html/training/wearables/apps/always-on.jd b/docs/html/training/wearables/apps/always-on.jd new file mode 100644 index 000000000000..21187e1f4722 --- /dev/null +++ b/docs/html/training/wearables/apps/always-on.jd @@ -0,0 +1,406 @@ +page.title=Keeping Your App Visible +page.tags=wear +helpoutsWidget=true + +@jd:body + +<div id="tb-wrapper"> +<div id="tb"> +<h2>This lesson teaches you to</h2> +<ol> + <li><a href="#EnableAmbient">Enable Ambient Mode in a Wearable App</a></li> + <li><a href="#UpdateContent">Update Content in Ambient Mode</a></li> + <li><a href="#BackwardCompatibility">Maintain Backward-compatibility</a></li> +</ol> +<h2>You should also read</h2> + <ul> + <li><a href="{@docRoot}design/wear/structure.html">App Structure for Android Wear</a></li> + </ul> +<h2>Related Samples</h2> + <ul> + <li><a href="//github.com/googlesamples/android-AlwaysOn">AlwaysOn</a></li> + </ul> +</div> +</div> + +<p>Some Wear apps are most useful when they are constantly visible to the user. For example, users +out on a run can glance at their wearable to see the distance covered and time elapsed, or after +recording a grocery list on their wearable, users can quickly see which items are remaining on the +list as they shop at the market. Making an app constantly visible has an impact on battery life, +so you should carefully consider that impact when adding this feature to your app. +</p> + +<p>Android Wear devices running Android version 5.1 or higher allow apps to remain in the +foreground while saving battery power. Android Wear apps can control what’s displayed on the +wearable device screen while the device is in a low-power ambient mode. Wear apps that run in both +ambient and interactive mode are called <i>always-on</i> apps. +</p> + +<p>This lesson describes how to enable your wearable app to be always-on, update the screen +while in ambient mode, and maintain backwards compatibility. +</p> + +<h2 id="EnableAmbient">Enable Ambient Mode in a Wearable App</h2> + +<p>For new and existing projects, you can add ambient mode support to your Wear app by updating +your development project configuration. After you complete the project configuration, extend the +<a href="{@docRoot}reference/android/support/wearable/activity/WearableActivity.html"><code>WearableActivity</code></a> +class, which provides all the methods you need to enable ambient mode in your app. The following +sections describe these steps in detail.</p> + +<h3 id="ConfigureProject">Configure your development project</h3> + +<p>In order to support ambient mode in your Wear app, you must update your Android SDK and configure +your development project. Follow these steps to make the necessary changes:</p> + +<ul> + <li>Update your SDK to include the Android 5.1 (API 22) or higher platform, which provides the + APIs to allow activities to go into ambient mode. For more information on how to update your SDK, + see + <a href="{@docRoot}sdk/installing/adding-packages.html#GetTools">Adding SDK Packages</a>. + </li> + <li> Create a project or modify an existing project to target Android 5.1 or higher. This means + you must set the manifest + <a href="{@docRoot}topics/manifest/uses-sdk-element.html"><code>targetSdkVersion</code></a> to 22 + or higher.</li> + <li>Set the manifest + <a href="{@docRoot}guide/topics/manifest/uses-sdk-element.html"><code>minSdkVersion</code></a> to + 20 or higher, if you want to support devices on versions prior to Android 5.1. For more + information on backwards compatibility, see + <a href="#BackwardCompatibility">Maintain Backward-compatibility</a>.</li> + </li> + <li>Add or update the following dependencies to your <code>build.gradle</code> file: +<pre> +dependencies { + ... + compile 'com.google.android.support:wearable:1.2.0' + provided 'com.google.android.wearable:wearable:1.0.0' +} +</pre> +<p class="note"><b>Note:</b> The <code>provided</code> dependency ensures that the classes loaded at +run-time to support ambient mode are also available at compile-time. +</p> +</li> + <li>Add the wearable shared library entry into the wearable app manifest: +<pre> +<application> + <uses-library android:name="com.google.android.wearable" + android:required="false" /> + ... +</application> +</pre> + </li> + <li>Add the + <a href="{@docRoot}reference/android/Manifest.permission.html#WAKE_LOCK"><code>WAKE_LOCK</code></a> + permission to the handheld and wearable app manifest: +<pre> +<uses-permission android:name="android.permission.WAKE_LOCK" /> +</pre> + </li> +</ul> + +<h3 id="CreateActivity">Create an activity that supports ambient mode</h3> + +<p>To enable ambient mode in your activity, use the +<a href="{@docRoot}reference/android/support/wearable/activity/WearableActivity.html"><code>WearableActivity</code></a> +class and methods. +</p> + +<ol> + <li>Create an activity that extends + <a href="{@docRoot}reference/android/support/wearable/activity/WearableActivity.html"><code>WearableActivity</code></a>.</li> + <li>In the + <a href="{@docRoot}reference/android/app/Activity.html#onCreate(android.os.Bundle)"><code>onCreate()</code></a> + method of your activity, call the + <a href="{@docRoot}reference/android/support/wearable/activity/WearableActivity.html#setAmbientEnabled()"><code>setAmbientEnabled()</code></a> + method.</li> +</ol> + +<p>Enable ambient mode in your activity as follows:</p> + +<pre> +public class MainActivity extends WearableActivity { + +@Override +public void onCreate(Bundle savedInstanceState) { + super.onCreate(savedInstanceState); + + <strong>setAmbientEnabled();</strong> + ... +} +</pre> + +<h3 id="EnableDisable">Handle transitions between modes</h3> + +<p>If the user does not interact with your app for a period of time while it is displayed, or if +the user covers the screen with their palm, the system switches the activity to ambient mode. +After the app switches to ambient mode, update the activity UI to a more basic layout to reduce +power consumption. You should use a black background with minimal white graphics and text. To +ease a user into the transition from interactive to ambient mode, try to maintain similar placement +of items on the screen. For more information on presenting content on an ambient screen, see the +<a href="{@docRoot}design/wear/watchfaces.html#DisplayModes">Watch Faces for Android Wear</a> +design guide. +</p> + +<p class="note"><b>Note:</b> In ambient mode, disable any interactive elements on the +screen, such as buttons. For more information on how to design user interactions for an always-on +app, see the +<a href="{@docRoot}design/wear/structure.html#AlwaysOn">App Structure for Android Wear</a> design +guide. +</p> + +<p>When the activity switches to ambient mode, the system calls the +<a href="{@docRoot}reference/android/support/wearable/activity/WearableActivity.html#onEnterAmbient(android.os.Bundle)"><code>onEnterAmbient()</code></a> +method in your wearable activity. The following code snippet shows how to change the text color to +white and disable anti-aliasing after the system switches to ambient mode: +</p> + +<pre> +@Override +public void onEnterAmbient(Bundle ambientDetails) { + super.onEnterAmbient(ambientDetails); + + mStateTextView.setTextColor(Color.WHITE); + mStateTextView.getPaint().setAntiAlias(false); +} +</pre> + +<p>When the user taps the screen or brings up their wrist, the activity switches from ambient mode +to interactive mode. The system calls the +<a href="{@docRoot}reference/android/support/wearable/activity/WearableActivity.html#onExitAmbient()"><code>onExitAmbient()</code></a> +method. Override this method to update the UI layout so that your app displays in a full-color, +interactive state.</p> + +<p>The following code snippet shows how to change the text color to green and enable anti-aliasing +when the system switches to interactive mode:</p> + +<pre> +@Override +public void onExitAmbient() { + super.onExitAmbient(); + + mStateTextView.setTextColor(Color.GREEN); + mStateTextView.getPaint().setAntiAlias(true); +} +</pre> + +<h2 id="UpdateContent">Update Content in Ambient Mode</h2> + +<p>Ambient mode allows you to update the screen with new information for the user, but you must +carefully balance display updates against the battery life. You should strongly consider only +overriding the +<a href="{@docRoot}reference/android/support/wearable/activity/WearableActivity.html#onUpdateAmbient()"><code>onUpdateAmbient()</code></a> +method to update the screen once a minute in ambient mode. If your app requires more frequent +updates, take into consideration that there is a trade-off between battery life and the frequency of +updates. To realize battery savings, updates should be no more than once every 10 seconds. In +practice, however, you should update your app less frequently than that. +</p> + +<h3 id="StandardRefresh">Update once a minute</h3> + +<p>In order to preserve battery power, most wear apps should not frequently update the screen while +in ambient mode. We recommend designing your app to update the screen once per minute while +in this mode. The system provides a callback method, +<a href="{@docRoot}reference/android/support/wearable/activity/WearableActivity.html#onUpdateAmbient()"><code>onUpdateAmbient()</code></a>, +that allows you to update the screen at this recommended frequency.</p> + +<p>To update your app content, override the +<a href="{@docRoot}reference/android/support/wearable/activity/WearableActivity.html#onUpdateAmbient()"><code>onUpdateAmbient()</code></a> +method in your wearable activity: +</p> + +<pre> +@Override +public void onUpdateAmbient() { + super.onUpdateAmbient(); + + // Update the content +} +</pre> + +<h3 id="CustomRefresh">Update more frequently</h3> + +<p>For apps that require more frequent updates, such as a fitness, time-keeping, and travel +information apps, use an +<a href="{@docRoot}reference/android/app/AlarmManager.html"><code>AlarmManager</code></a> +object to wake the processor and update the screen more frequently.</p> + +<p>To implement an alarm that updates content more frequently in ambient mode, follow these steps: +</p> + +<ol> + <li>Prepare the alarm manager.</li> + <li>Set the frequency of the updates.</li> + <li>Schedule the next update when the activity switches to ambient mode or is currently in ambient + mode.</li> + <li>Cancel the alarm when the activity switches to interactive mode or the activity is stopped + </li> +</ol> + +<p class="note"><b>Note:</b> The alarm manager may create new instances of your activity as they are +triggered. To prevent this situation, ensure that your activity is declared with the +<code>android:launchMode="singleInstance"</code> parameter in the manifest.</p> + +<p>The following sections describe these steps in detail.</p> + +<h4 id="PrepareAlarm">Prepare the alarm manager</h4> + +<p>The alarm manager launches a pending intent that updates the screen and schedules the next alarm. +The following example shows how to declare the alarm manager and the pending intent in the +<a href="{@docRoot}reference/android/app/Activity.html#onCreate(android.os.Bundle)"><code>onCreate()</code></a> +method of your activity:</p> + +<pre> +private AlarmManager mAmbientStateAlarmManager; +private PendingIntent mAmbientStatePendingIntent; + +@Override +public void onCreate(Bundle savedInstanceState) { + super.onCreate(savedInstanceState); + + setAmbientEnabled(); + + mAmbientStateAlarmManager = + (AlarmManager) getSystemService(Context.ALARM_SERVICE); + Intent ambientStateIntent = + new Intent(getApplicationContext(), MainActivity.class); + + mAmbientStatePendingIntent = PendingIntent.getActivity( + getApplicationContext(), + 0, + ambientStateIntent, + PendingIntent.FLAG_UPDATE_CURRENT); + ... +} +</pre> + +<p>When the alarm triggers and launches the pending intent, update the screen and schedule the next +alarm by overriding the +<a href="{@docRoot}reference/android/app/Activity.html#onNewIntent(android.content.Intent)"><code>onNewIntent()</code></a> +method: +</p> + +<pre> +@Override +public void onNewIntent(Intent intent) { + super.onNewIntent(intent); + + setIntent(intent); + + // Described in the following section + refreshDisplayAndSetNextUpdate(); +} +</pre> + +<h4 id="ScheduleUpdates">Update screen and schedule data updates</h4> + +<p>In this example activity, the alarm manager triggers every 20 seconds in ambient mode. When +the timer ticks, the alarm triggers the intent to update the screen and then sets the delay for the +next update. +</p> + +<p>The following example shows how to update information on the screen and set the alarm for the +next update: +</p> + +<pre> +// Milliseconds between waking processor/screen for updates +private static final long AMBIENT_INTERVAL_MS = TimeUnit.SECONDS.toMillis(20); + +private void refreshDisplayAndSetNextUpdate() { + + if (isAmbient()) { + // Implement data retrieval and update the screen for ambient mode + } else { + // Implement data retrieval and update the screen for interactive mode + } + + long timeMs = System.currentTimeMillis(); + + // Schedule a new alarm + if (isAmbient()) { + // Calculate the next trigger time + long delayMs = AMBIENT_INTERVAL_MS - (timeMs % AMBIENT_INTERVAL_MS); + long triggerTimeMs = timeMs + delayMs; + + mAmbientStateAlarmManager.setExact( + AlarmManager.RTC_WAKEUP, + triggerTimeMs, + mAmbientStatePendingIntent); + + } else { + // Calculate the next trigger time for interactive mode + } +} +</pre> + +<h4 id="ScheduleNext">Schedule the next alarm</h4> + +<p>Schedule the alarm to update the screen when the activity is entering ambient mode or when the +activity is already in ambient mode by overriding the +<a href="{@docRoot}reference/android/support/wearable/activity/WearableActivity.html#onEnterAmbient(android.os.Bundle)"><code>onEnterAmbient()</code></a> +method and the +<a href="{@docRoot}reference/android/support/wearable/activity/WearableActivity.html#onUpdateAmbient()"><code>onUpdateAmbient()</code></a> +method:</p> + +<pre> +@Override +public void onEnterAmbient(Bundle ambientDetails) { + super.onEnterAmbient(ambientDetails); + + refreshDisplayAndSetNextUpdate(); +} + +@Override +public void onUpdateAmbient() { + super.onUpdateAmbient(); + + refreshDisplayAndSetNextUpdate(); +} +</pre> + +<p class="note"><b>Note:</b> In this example, the <code>refreshDisplayAndSetNextUpdate()</code> +method is called whenever the screen needs to be updated. For more examples of when to call this +method, see the <a href="//github.com/googlesamples/android-AlwaysOn">AlwaysOn</a> sample. +</p> + +<h4 id="CancelAlarm">Cancel the alarm</h4> + +<p>When the device switches to interactive mode, cancel the alarm in the +<a href="{@docRoot}reference/android/support/wearable/activity/WearableActivity.html#onExitAmbient()"><code>onExitAmbient()</code></a> +method:</p> + +<pre> +@Override +public void onExitAmbient() { + super.onExitAmbient(); + + mAmbientStateAlarmManager.cancel(mAmbientStatePendingIntent); +} +</pre> + +<p>When the user exits or stops your activity, cancel the alarm in the +<a href="{@docRoot}reference/android/app/Activity.html#onDestroy()"><code>onDestroy()</code></a> +method of your activity:</p> + +<pre> +@Override +public void onDestroy() { + mAmbientStateAlarmManager.cancel(mAmbientStatePendingIntent); + super.onDestroy(); +} +</pre> + +<h2 id="BackwardCompatibility">Maintain Backward-compatibility</h2> + +<p>Activities that support ambient mode automatically fall back to normal activities on Wear devices +that are on Android versions prior to 5.1 (API level 22). No special app code is required to support +devices on these versions of Android. When the device switches to ambient mode, the device returns +to the home screen and exits your activity.</p> + +<p>If your app should not be installed or updated on devices with Android versions prior to 5.1, +update your manifest with the following:</p> + +<pre> +<uses-library android:name="com.google.android.wearable" android:required="true" /> +</pre> diff --git a/docs/html/training/wearables/apps/index.jd b/docs/html/training/wearables/apps/index.jd index 812f8936eefc..e2a71de639c9 100644 --- a/docs/html/training/wearables/apps/index.jd +++ b/docs/html/training/wearables/apps/index.jd @@ -6,12 +6,12 @@ page.image=wear/images/01_create.png @jd:body <div id="tb-wrapper"> -<div id="tb"> - <h2>Dependencies and Prerequisites</h2> - <ul> - <li>Android Studio 0.8 or later and Gradle 0.12 or later</li> - </ul> -</div> + <div id="tb"> + <h2>Dependencies and Prerequisites</h2> + <ul> + <li>An Android Wear device</li> + </ul> + </div> </div> <p> @@ -21,10 +21,6 @@ differ greatly in design and usability and the amount of functionality provided. These are the main differences between handheld and wearable apps:</p> <ul> - <li>The system enforces a timeout period. If you are displaying an activity and user's don't - interact with it, the device sleeps. When it wakes back up, the Wear home screen is displayed - instead of your activity. If you need to show something persistent, create a notification in the - context stream instead.</li> <li>Wearable apps are relatively small in size and functionality compared to handheld apps. They contain only what makes sense on the wearable, which is usually a small subset of the corresponding handheld app. In general, you should carry out operations on the @@ -50,6 +46,26 @@ These are the main differences between handheld and wearable apps:</p> </li> </ul> +<p>To conserve power on a wearable device, you can enable ambient mode for your Wear app. +Devices transition from interactive to ambient mode when the user is idle on an activity or when +the user covers the screen with their palm. Wearable apps that can transition into ambient mode are +called <i>always-on</i> apps. The following describes the two modes of operation for always-on apps: +</p> +<dl> + <dt><strong>Interactive</strong></dt> + <dd>Use full color with fluid animation in this mode. The app is also responsive to + input.</dd> + <dt><strong>Ambient</strong></dt> + <dd>Render the screen with grayscale graphics and do not present any input cues in this mode. + This display mode is only supported on devices running Android 5.1 or higher.</dd> +</dl> + +<p>On devices running versions prior to Android 5.1 or for apps that do not support ambient mode, +when a user is idle on an activity or when the user covers the screen with their palm on an +activity, the Wear home screen is displayed instead of your activity in ambient mode. If you +need to show persistent content on versions prior to Android 5.1, create a notification in the +context stream instead.</p> + <p class="note"><b>Note:</b> We recommend using Android Studio for Android Wear development as it provides project setup, library inclusion, and packaging conveniences that aren't available in ADT. The rest of this training assumes you're using Android Studio. @@ -64,6 +80,9 @@ in ADT. The rest of this training assumes you're using Android Studio. <dt><a href="{@docRoot}training/wearables/apps/layouts.html">Creating Custom Layouts</a></dt> <dd>Learn how to create and display custom layouts for notifications and activities.</dd> + <dt><a href="{@docRoot}training/wearables/apps/always-on.html">Keeping Your App Visible</a></dt> + <dd>Learn how to enable ambient mode for your apps, so they remain visible while still saving + battery power.</dd> <dt><a href="{@docRoot}training/wearables/apps/voice.html">Adding Voice Capabilities</a></dt> <dd>Learn how to launch an activity with voice actions and how to start the system speech recognizer app to obtain free-form voice input.</dd> diff --git a/docs/html/wear/images/partners/tagheuer.png b/docs/html/wear/images/partners/tagheuer.png Binary files differnew file mode 100644 index 000000000000..507f90c3953b --- /dev/null +++ b/docs/html/wear/images/partners/tagheuer.png diff --git a/docs/html/wear/index.jd b/docs/html/wear/index.jd index 316f5ca03881..14a9bbf7d10f 100644 --- a/docs/html/wear/index.jd +++ b/docs/html/wear/index.jd @@ -246,6 +246,9 @@ page.type=about <div class="col-4"> <img src="/wear/images/partners/sony.png" alt="Sony"> </div> + <div class="col-4"> + <img src="/wear/images/partners/tagheuer.png" alt="Tag Heuer"> + </div> </div> </div> <!-- end .wrap --> </div> |
