diff options
Diffstat (limited to 'docs/html')
31 files changed, 595 insertions, 337 deletions
diff --git a/docs/html/auto/images/assets/do_05_template.png b/docs/html/auto/images/assets/do_05_template.png Binary files differindex 4e11243..379253d 100644 --- a/docs/html/auto/images/assets/do_05_template.png +++ b/docs/html/auto/images/assets/do_05_template.png diff --git a/docs/html/auto/index.jd b/docs/html/auto/index.jd index 09374ad..2c0334e 100644 --- a/docs/html/auto/index.jd +++ b/docs/html/auto/index.jd @@ -44,59 +44,13 @@ page.type=about .auto-img-frame-cols { z-index:2; position:relative; + width:460px; } .auto-img-shot-cols { + width:447px; position:absolute; - top:5px; - left:2px; - z-index:1; -} -</style> - - - <style> -.fullpage>#footer, -#jd-content>.content-footer.wrap { - display:none; -} -</style> - -<style> -#footer { - display: none; -} -.content-footer { - display: none; -} -#hero-height { - height:calc(100% - 110px); -} -.img-logo { - margin:0 auto; - display:block; - margin-bottom:-28px !important; -} -.img-logo-thin { - margin:0 auto; - display:block; - margin-bottom:-55px !important; -} -.col-5 { - width:170px; -} -.auto-img-container-cols { - position:relative; - margin-bottom:25px; - margin-top:25px; -} -.auto-img-frame-cols { - z-index:2; - position:relative; -} -.auto-img-shot-cols { - position:absolute; - top:5px; - left:2px; + top:8px; + left:7px; z-index:1; } </style> @@ -214,8 +168,8 @@ page.type=about <div class="landing-section-header"> <div class="landing-h1">Minimize Distraction</div> <div class="landing-subhead"> - Standard UI templates for several app categories let users focus on the road. - </div> + Standard UI templates for several app categories let users focus on the road. + </div> </div> <div class="landing-body"> <div class="cols"> diff --git a/docs/html/auto/overview.jd b/docs/html/auto/overview.jd index 728dff7..6c02641 100644 --- a/docs/html/auto/overview.jd +++ b/docs/html/auto/overview.jd @@ -31,18 +31,16 @@ page.metaDescription=Android Auto margin-top:10px; } .auto-img-frame-cols { + width:380px; z-index:2; position:relative; } .auto-img-shot-cols { + width:369px; position:absolute; - top:0px; - left:0px; + top:7px; + left:6px; z-index:1; - border:1px solid #; - -webkit-border-radius: 7px; - -moz-border-radius: 7px; - border-radius: 7px; } .auto-col-2 { width:380px; @@ -89,27 +87,33 @@ page.metaDescription=Android Auto <h1>Android Auto Developer Overview</h1> -<p>Android Auto extends the Android platform to car entertainment systems. When users connect -their Android handheld device to a compatible vehicle, Android Auto lets users project apps on -the vehicle’s touchscreen and interact with them using the vehicle’s controls.</p> +<p>Android Auto extends the Android platform into the car. When users connect +their Android handheld device to a compatible vehicle, Android Auto provides a car-optimized +Android experience on the vehicle's screen. Users interact with compatible apps and services +through voice actions and the vehicle's input controls.</p> + +<p>The Android Auto SDK lets you easily extend your existing apps to work in the car, without +having to worry about vehicle-specific hardware differences. You can use many Android APIs and +services you are already familiar with. Android Auto provides easy to use UI templates and +supports notifications and voice actions:</p> <dl> <dt style="margin-bottom:10px"><strong>UI Templates</strong></dt> <dd style="margin-bottom:20px"> -Android Auto defines interaction models and UI templates for several app categories. The +Android Auto defines interaction models and UI templates for apps. The first version of Android Auto supports media apps, such as music, podcast, live radio, and -audio news apps. Future versions will support messaging, communication, local search apps, -and more. +audio news apps. </dd> <dt style="margin-bottom:10px"><strong>Notifications</strong></dt> <dd style="margin-bottom:20px"> The platform will integrate with existing Android APIs for notifications. Users will get -some notifications from Android apps on the vehicle’s screen.</dd> +car appropiate notifications from Android apps on the vehicle's screen.</dd> <dt style="margin-bottom:10px"><strong>Voice Actions</strong></dt> <dd style="margin-bottom:20px"> -Android Auto supports voice search and voice actions for media apps. Future versions -will support additional voice actions.</dd> +Android Auto supports a set of voice actions to interact with compatible apps and services. +Apps can respond to the voice actions they're interested in, such as playing a particular song +or taking a note.</dd> <dt style="margin-bottom:10px"><strong>Easy Development Workflow</strong></dt> <dd style="margin-bottom:20px"> @@ -124,39 +128,52 @@ Android Auto experience on a regular Android device.</p> <h2 id="design">Design</h2> -<p>Digital experiences for cars should complement and augment driving, not demand the driver's -attention. Designing these experiences for cars is fundamentally different than in the case of -phones and tablets. It requires rethinking how these experiences unfold.</p> +<p>Android Auto extends users' digital ecosystem into their cars, allowing drivers to stay +connected to their virtual worlds while staying focused on the road ahead.</p> + +<p>Because driving is the primary activity in the car, any digital experiences should be designed +to complement and augment that activity. They should never demand the user's attention.</p> -<h3 id="designprinciples">Design Principles</h3> +<p>Designing for cars is fundamentally different than designing for phones or tablets, and +requires rethinking how experiences unfold. Because attention is limited and not all tasks are +possible in the car, effective apps leverage the entire set of devices that drivers have, +leveraging the app experience on those devices, outside of the car, to set the stage for simple +experiences while driving.</p> -<p><strong>Glanceable</strong>. We designed Android Auto to reduce UI complexity, optimize user -interactions, and lower cognitive load. Effective apps show just enough information -and only provide features that do not require excessive menu interaction and navigation.</p> +<p>Android Auto experiences are:</p> + +<p><strong>Glanceable and simple</strong>. Driving requires users' full attention. In-car software +should not. Android Auto was designed to simplify not only the UI, but to optimize interactions +and require less thinking, induce lower cognitive load, and ultimately, be safer. Effective apps +provide just enough information in the minimum amount of time the user needs to glance at it and +return their attention back to the road. Apps should also reduce the number of features to only +those that are safe and drive-appropriate.</p> <p><strong>Predictive, yet predictable</strong>. Android Auto leverages rich, contextual awareness -to keep the driver informed about important situations. Timely help is combined with predictable -functions. Effective apps use patterns for common tasks and show timely information only when -relevant.</p> +to keep the driver informed about important situations during the drive. Rich, timely help is +combined with predictable functions. Effective apps make use of the patterns for common tasks and +show timely information only when relevant.</p> + +<p><strong>Connected</strong>. By leveraging the user's personal ecosystem of apps and services, +Android Auto promotes a continuous experience from phone to car to other devices. The user's +music, destinations, and virtual ecosystem are always available to augment the drive. Experiences +that leverage personal context and other devices are naturally part of Android Auto.</p> -<p><strong>Connected</strong>. Android Auto works with apps that drivers already use in other -devices. Android Auto promotes a continuous app experience from phones and tablets to cars, -providing access to user's existing settings, subscriptions, and digital libraries. Experiences -that bring personal content and context from other devices are part of Android Auto.</p> +<p><strong>Naturally integrated</strong>. Android Auto blends the user's apps with the car, +creating a truly integrated experience that leverages what is unique about each car. By using +the screens, controls, and capabilities of the vehicle, Android Auto feels like an extension of +the car.</p> -<p><strong>Integrated</strong>. Android Auto blends your apps with the vehicle's entertainment -system, creating a truly integrated experience in every car. By using the vehicle's screen and -controls, apps feel tailored to each car.</p> <h2 id="architecture">Architecture</h2> -<p>The Android Auto app projects your app's customized UI on the vehicle's screen. To communicate +<p>The Android Auto app shows your app's customized UI on the vehicle's screen. To communicate with the Android Auto app, your media app implements a set of media interfaces.</p> <div style="width:750px;margin:0 auto"> -<img src="{@docRoot}auto/images/figure01.png" alt="" id="figure1" /> +<img src="{@docRoot}auto/images/figure01.png" alt="" /> <p class="img-caption"> <strong>Figure 1</strong> - Architecture of Android Auto. </p> @@ -215,11 +232,9 @@ Android device and lets users select one of them from an scrollable list:</p> <h3>Primary App Template</h3> -<p>After the user selects a media app, the display shows the primary app template. Figure -3 shows the elements of this template that you can customize:</p> - -<p>You can customize the primary app template to show your own icons, app name, and -background images. Figure 4 shows an example of a customized template:</p> +<p>After the user selects a media app, the display shows the primary app template. +You can customize this template to show your own icons, app name, and +background images. Figure 3 shows an example of a customized template:</p> <div class="cols"> <div class="auto-col-2"> @@ -236,7 +251,7 @@ background images. Figure 4 shows an example of a customized template:</p> </div> </div> <p class="img-caption"> - <strong>Figure 4.</strong> A customized template. + <strong>Figure 3.</strong> A customized template. </p> @@ -245,7 +260,7 @@ background images. Figure 4 shows an example of a customized template:</p> <p>The primary app template supports four main actions on the action bar, four auxiliary actions on the overflow bar, and the <em>Return</em> action. You can use standard controls and customize -the actions and icons, as shown in Figure 5.</p> +the actions and icons, as shown in Figure 4.</p> <div class="auto-img-container-single"> <div class="auto-img-container"> @@ -253,18 +268,14 @@ the actions and icons, as shown in Figure 5.</p> <img class="auto-img-shot-cols" src="/auto/images/assets/do_03_more.png" /> </div> <p class="img-caption" style="margin-top:0px"> - <strong>Figure 5.</strong> Custom extra actions. + <strong>Figure 4.</strong> Custom extra actions. </p> </div> <h3 id="drawertransitions">Drawer Transitions</h3> -<p>For browse actions, the display shows the drawer transition and template:</p> - -<p>After the transition from the primary app template to the drawer template, the drawer -appears on the center. The customized drawer template shows the media containers and -media files provided by the media service in your app. You can also customize drawers -with icons for list items.</p> +<p>For browse actions, the display shows the drawer transition and template, as shown in +Figure 5.</p> <div class="cols"> <div class="auto-col-2"> @@ -281,13 +292,19 @@ with icons for list items.</p> </div> </div> <p class="img-caption"> - <strong>Figure 4.</strong> Generic and customized drawer templates. + <strong>Figure 5.</strong> Generic and customized drawer templates. </p> +<p>After the transition from the primary app template to the drawer template, the drawer +appears on the center. The customized drawer template shows the media containers and +media files provided by the media service in your app. You can also customize drawers +with icons for list items.</p> + + <h3 id="daynighttransitions">Day and Night Transitions</h3> -<p>All the templates support different color schemes for day and night, as shown in -Figure 8. The platform provides the state (day or night) and makes adjustments automatically.</p> +<p>All the templates support different color schemes for day and night. +The platform provides the state (day or night) and makes adjustments automatically.</p> <h3 id="customizetemplates">Customizing Templates</h3> diff --git a/docs/html/google/gcm/ccs.jd b/docs/html/google/gcm/ccs.jd index 03addfd..4389e3d 100644 --- a/docs/html/google/gcm/ccs.jd +++ b/docs/html/google/gcm/ccs.jd @@ -19,7 +19,11 @@ page.title=GCM Cloud Connection Server (XMPP) <li><a href="#response">Response format</a></li> </ol> </li> - <li><a href="#upstream">Upstream Messages</a> </li> + <li><a href="#upstream">Upstream Messages</a> + <ol> + <li><a href="#receipts">Receive return receipts</a></li> + </ol> + </li> <li><a href="#flow">Flow Control</a> </li> <li><a href="#implement">Implementing an XMPP-based App Server</a> <ol class="toc"> @@ -43,9 +47,6 @@ target="_android">CCS and User Notifications Signup Form</a></li> </div> </div> -<p class="note"><strong>Note:</strong> To try out this feature, sign up using -<a href="https://services.google.com/fb/forms/gcm/">this form</a>.</p> - <p>The GCM Cloud Connection Server (CCS) is an XMPP endpoint that provides a persistent, asynchronous, bidirectional connection to Google servers. The connection can be used to send and receive messages between your server and @@ -149,8 +150,8 @@ exceptions:</p> <li>CCS adds the field {@code message_id}, which is required. This ID uniquely identifies the message in an XMPP connection. The ACK or NACK from CCS uses the {@code message_id} to identify a message sent from 3rd-party app servers to CCS. -Therefore, it's important that this {@code message_id} not only be unique, but -always present.</li> +Therefore, it's important that this {@code message_id} not only be unique (per +sender ID), but always present.</li> </ul> <p>In addition to regular GCM messages, control messages are sent, indicated by @@ -188,7 +189,8 @@ parameters and which connection server(s) supports them.</p> "hello":"world", } "time_to_live":"600", - "delay_while_idle": true/false + "delay_while_idle": true/false, + "delivery_receipt_requested": true/false } </gcm> </message> @@ -227,42 +229,48 @@ message is "nack". A NACK message contains:</p> <p>Below are some examples.</p> <p>Bad registration:</p> + <pre><message> - <data:gcm xmlns:data="google:mobile:data"> + <gcm xmlns="google:mobile:data"> { - "error":"BAD_REGISTRATION", // error code + "message_type":"nack", "message_id":"msgId1", - "from":"PA91bHFOtaQGSwupt5l1og", - "message_type":"nack" + "from":"SomeInvalidRegistrationId", + "error":"BAD_REGISTRATION", + "error_description":"Invalid token on 'to' field: SomeInvalidRegistrationId" } - </data:gcm> + </gcm> </message></pre> -<p>Invalid "time to live":</p> +<p>Invalid JSON:</p> <pre><message> - <data:gcm xmlns:data="google:mobile:data"> - { - "error":"InvalidJson : INVALID_TTL : Invalid value (-1) for \"time_to_live\": must be between 0 and \"2419200\"\n", - "message_id":"msgId1", - "from":"APA91bHFOtaQGSwupt5l1og", - "message_type":"nack" - } - </data:gcm> -</message></pre> + <gcm xmlns="google:mobile:data"> + { + "message_type":"nack", + "message_id":"msgId1", + "from":"APA91bHFOtaQGSwupt5l1og", + "error":"INVALID_JSON", + "error_description":"InvalidJson: JSON_TYPE_ERROR : Field \"time_to_live\" must be a JSON java.lang.Number: abc" + } + </gcm> +</message> +</pre> -<p>JSON type error:</p> +<p>Quota exceeded:</p> <pre><message> - <data:gcm xmlns:data="google:mobile:data"> - { - "error":"InvalidJson : JSON_TYPE_ERROR : Field \"delay_while_idle\" must be a JSON java.lang.Boolean: not-boolean-user-supplied-value\n", - "message_id":"msgId1", - "from":"APA91bHFOtaQGSwupt5l1og", - "message_type":"nack" - } - </data:gcm> -</message></pre> + <gcm xmlns="google:mobile:data"> + { + "message_type":"nack", + "message_id":"msgId1", + "from":"APA91bHFOtaQGSwupt5l1og", + "error":"QUOTA_EXCEEDED", + "error_description":"Short-term downstream quota exceeded for this registration id" + } + </gcm> +</message> +</pre> <p>The following table lists NACK error codes. Unless otherwise @@ -300,7 +308,7 @@ message should be immediately retried over another connection.</td> </tr> <tr> <td>{@code INVALID_JSON}</td> -<td>The JSON message payload was not valid.</td> +<td>The JSON message payload is not valid.</td> </tr> <tr> <td>{@code QUOTA_EXCEEDED}</td> @@ -309,10 +317,10 @@ sender/device pair) is too high. If you want to retry the message, try using a s rate.</td> </tr> <tr> -<td>{@code SERVICE_UNAVAILABLE}</td> -<td>CCS is not currently able to process the message. The -message should be retried over the same connection using exponential backoff -with an initial delay of 1 second.</td> + <td>{@code SERVICE_UNAVAILABLE}</td> + <td>CCS is not currently able to process the message. The + message should be retried over the same connection using exponential backoff + with an initial delay of 1 second.</td> </tr> </table> @@ -382,8 +390,8 @@ Bundle data = new Bundle(); // Bundle data consists of a key-value pair data.putString("hello", "world"); // "time to live" parameter -// This is optional. It specifies a value in seconds up to 4 weeks. -int ttl = [0 seconds, 4 weeks] +// This is optional. It specifies a value in seconds up to 24 hours. +int ttl = [0 seconds, 24 hours] gcm.send(GCM_SENDER_ID + "@gcm.googleapis.com", id, ttl, data); </pre> @@ -419,6 +427,69 @@ response to the above message:</p> </gcm> </message></pre> +<h3 id="receipts">Receive return receipts</h3> + +<p>You can use upstream messaging to get receipt notifications, confirming +that a given message was sent to a device. Your 3rd-party app server receives the receipt +notification from CCS once the message has been sent to the device.</p> + +<p>To enable this feature, the message your 3rd-party app server sends to CCS must include +a field called <code>"delivery_receipt_requested"</code>. When this field is set to +<code>true</code>, CCS sends a return receipt. Here is an XMPP stanza containing a JSON +message with <code>"delivery_receipt_requested"</code> set to <code>true</code>:</p> + +<pre><message id=""> + <gcm xmlns="google:mobile:data"> + { + "to":"REGISTRATION_ID", + "message_id":"m-1366082849205" + "data": + { + "hello":"world", + } + "time_to_live":"600", + "delay_while_idle": true, + <strong>"delivery_receipt_requested": true</strong> + } + </gcm> +</message> +</pre> + +<p>Here is an example of a receipt notification message that CCS sends back to your 3rd-party +app server:</p> + +</p> +<pre><message id=""> + <gcm xmlns="google:mobile:data"> + { + "category":"com.example.yourapp", // to know which app sent it + "data": + { + “message_status":"MESSAGE_SENT_TO_DEVICE", + “original_message_id”:”m-1366082849205” + “device_registration_id”: “REGISTRATION_ID” + }, + "message_id":"dr2:m-1366082849205", + "message_type":"receipt", + "from":"gcm.googleapis.com" + } + </gcm> +</message></pre> + +<p>Note the following:</p> + +<ul> + <li>The {@code "message_type"} is set to {@code "receipt"}. + <li>The {@code "message_status"} is set to {@code "MESSAGE_SENT_TO_DEVICE"}, + indicating that the message was delivered. Notice that in this case, +{@code "message_status"} is not a field but rather part of the data payload.</li> + <li>The receipt message ID consists of the original message ID, but with a +<code>dr:</code> prefix. Your 3rd-party app server must send an ACK back with this ID, +which in this example is {@code dr2:m-1366082849205}.</li> + <li>The original message ID and status are inside the +{@code "data"} field.</li> +</ul> + <h2 id="flow">Flow Control</h2> <p>Every message sent to CCS receives either an ACK or a NACK response. Messages diff --git a/docs/html/google/gcm/client.jd b/docs/html/google/gcm/client.jd index 42cebfc..ec7e748 100644 --- a/docs/html/google/gcm/client.jd +++ b/docs/html/google/gcm/client.jd @@ -246,7 +246,8 @@ private boolean checkPlayServices() { <h3 id="sample-register">Register for GCM</h3> <p>An Android application needs to register with GCM servers before it can receive messages. When an app registers, it receives a registration ID, which it can then -store for future use. In the following snippet the {@code onCreate()} method in the sample app's +store for future use (note that registration IDs must be kept secret). In the +following snippet the {@code onCreate()} method in the sample app's main activity checks to see if the app is already registered with GCM and with the server:</p> diff --git a/docs/html/google/gcm/gcm.jd b/docs/html/google/gcm/gcm.jd index 88bf659..19151b9 100644 --- a/docs/html/google/gcm/gcm.jd +++ b/docs/html/google/gcm/gcm.jd @@ -123,7 +123,7 @@ it to receive messages. Once the Android application has the registration ID, it it to the 3rd-party application server, which uses it to identify each device that has registered to receive messages for a given Android application. In other words, a registration ID is tied to a particular Android application running on a particular -device. +device. Note that registration IDs must be kept secret. <br/> <br/> <strong>Note:</strong> If you use diff --git a/docs/html/google/gcm/index.jd b/docs/html/google/gcm/index.jd index 8f325b8..1f05a71 100644 --- a/docs/html/google/gcm/index.jd +++ b/docs/html/google/gcm/index.jd @@ -14,7 +14,10 @@ header.hide=1 <h1 itemprop="name" style="margin-bottom:0;">Google Cloud Messaging for Android</h1> <p itemprop="description"> Google Cloud Messaging for Android (GCM) is a service that allows you to send data -from your server to your users' Android-powered device, and also to receive messages from devices on the same connection. The GCM service handles all aspects of queueing of messages and delivery to the target Android application running on the target device. GCM is completely free no matter how big your messaging needs are, and there are no quotas. +from your server to your users' Android-powered device, and also to receive messages from +devices on the same connection. The GCM service handles all aspects of queueing of messages +and delivery to the target Android application running on the target device. GCM is +completely free no matter how big your messaging needs are, and there are no quotas. </p> </div> @@ -27,31 +30,39 @@ from your server to your users' Android-powered device, and also to receive mess <p>This could be a lightweight message telling your app there is new data to be fetched from the server (for instance, a movie uploaded by a friend), or it could be a message containing -up to 4kb of payload data (so apps like instant messaging can consume the message directly). <a href="{@docRoot}google/gcm/gcm.html">GCM Architectural Overview.</a></p> +up to 4kb of payload data (so apps like instant messaging can consume the message directly). +<a href="{@docRoot}google/gcm/gcm.html">GCM Architectural Overview.</a></p> <h4>Send "send-to-sync" messages</h4> - <p>A send-to-sync (collapsible) message is often a "tickle" that tells a mobile application to sync data from the server. For example, suppose you have an email application. When a user receives new email on the server, the server pings the mobile application with a "New mail" message. This tells the application to sync to the server to pick up the new email. - <a href="{@docRoot}google/gcm/adv.html#s2s">Send-to-sync messages</a>.</p> - </a> + <p>A send-to-sync (collapsible) message is often a "tickle" that tells a mobile + application to sync data from the server. For example, suppose you have an email + application. When a user receives new email on the server, the server pings the mobile + application with a "New mail" message. This tells the application to sync to the server + to pick up the new email. + <a href="{@docRoot}google/gcm/adv.html#s2s">Learn more »</a></p> <h4>Send messages with payload</h4> - <p>Unlike a send-to-sync message, every "message with payload" (non-collapsible message) is delivered. The payload the message contains can be up to 4kb. - <a href="{@docRoot}google/gcm/adv.html#payload">Messages with payload</a>.</p> + <p>Unlike a send-to-sync message, every "message with payload" (non-collapsible message) + is delivered. The payload the message contains can be up to 4kb. + <a href="{@docRoot}google/gcm/adv.html#payload">Learn more »</a></p> </div> <div class="col-6 normal-links"> <h3 style="clear:left">New Features</h3> - <h4>Faster, easier GCM setup</h4> - <p>Streamlined registration makes it simple and fast to add GCM support to your Android app. <a href="{@docRoot}google/gcm/gs.html">Learn more »</a></p> - <h4>Upstream messaging over XMPP</h4> - <p>GCM's Cloud Connection Service (CCS) lets you communicate with Android devices over a persistent XMPP connection. The primary advantages of CCS are speed, and the ability to receive upstream messages (that is, messages from a device to the cloud). You can use the service in tandem with existing GCM APIs. Use <a href="https://services.google.com/fb/forms/gcm/">this form</a> to sign up for CCS. <a href="{@docRoot}google/gcm/ccs.html">Learn more »</a></p> - <h4>Seamless multi-device messaging</h4> - <p>Maps a single user to a notification key, which you can then use to send a single message to multiple devices owned by the user. Use <a href="https://services.google.com/fb/forms/gcm/">this form</a> to sign up for User Notifications. <a href="{@docRoot}google/gcm/notifications.html">Learn more »</a></p> + + + <h4>Return Receipts</h4> + <p>You can use upstream messaging to get receipt notifications, confirming that a given + message was sent to a device. Your 3rd-party app server receives the receipt notification + from CCS once the message has been sent to the device. + <a href="{@docRoot}google/gcm/ccs.html#receipts">Learn more »</a></p> + <h4>Get Started</h4> - <p>Get started using the new features with a tutorial that walks you through creating a GCM app. <a href="{@docRoot}google/gcm/gs.html">Learn more »</a></p> + <p>Get started with a tutorial that walks you through creating a GCM app. + <a href="{@docRoot}google/gcm/gs.html">Learn more »</a></p> </div> </div> diff --git a/docs/html/google/gcm/notifications.jd b/docs/html/google/gcm/notifications.jd index 43a7368..2815f3d 100644 --- a/docs/html/google/gcm/notifications.jd +++ b/docs/html/google/gcm/notifications.jd @@ -14,8 +14,8 @@ page.title=User Notifications <h2>In this document</h2> <ol class="toc"> - <li><a href="#request">Request Format</a></li> - <li><a href="#create">Generate a Notification Key</a></li> + <li><a href="#gen-server">Generate a Notification Key on the Server</a></li> + <li><a href="#gen-client">Generate a Notification Key on the Client</a></li> <li><a href="#add">Add Registration IDs</a></li> <li><a href="#remove">Remove Registration IDs</a></li> <li><a href="#upstream">Send Upstream Messages</a></li> @@ -31,15 +31,11 @@ page.title=User Notifications <ol class="toc"> <li><a href="{@docRoot}google/gcm/gs.html">Getting Started</a></li> -<li><a href="https://services.google.com/fb/forms/gcm/" class="external-link" target="_android">CCS and User Notifications Signup Form</a></li> </ol> </div> </div> -<p class="note"><strong>Note:</strong> To try out this feature, sign up using <a href="https://services.google.com/fb/forms/gcm/">this form</a>.</p> - - <p>With user notifications, 3rd-party app servers can send a single message to multiple instance of an app running on devices owned by a single user. This feature is called <em>user notifications</em>. User notifications make it possible for every @@ -76,27 +72,23 @@ and then reconciling it with the corresponding notification. <p>You can use this feature with either the <a href="ccs.html">XMPP</a> (CCS) or <a href="http.html">HTTP</a> connection server.</p> +<p>You can generate notification keys in two different ways: on the server, and on +the client, if the user has a Google account. All of the associated registration IDs +can be mapped to a single user.</p> <p>The examples below show you how to perform generate/add/remove operations, and how to send upstream messages. For generate/add/remove operations, the message body is JSON.</p> -<h2 id="request">Request Format</h2> -<p>To send a message, the application server issues a POST request to -<code>https://android.googleapis.com/gcm/notification</code>.</p> +<h2 id="gen-server">Generate a Notification Key on the Server</h2> -<p>Here is the HTTP request header you should use for all create/add/remove operations:</p> - -<pre>content-type: "application/json" -Header : "project_id": <projectID> -Header: "Authorization", "key=API_KEY" -</pre> - -<h2 id="create">Generate a Notification Key</h2> +<p>To generate a notification key on the server, you create a new +create a new <code>notification_key</code> and map it to a +<code>notification_key_name</code>.</p> <p>This example shows how to create a new <code>notification_key</code> for a <code>notification_key_name</code> called <code>appUser-Chris</code>. -The {@code notification_key_name} is a name or identifier (can be a username for +The {@code notification_key_name} is a name or identifier (it can be a username for a 3rd-party app) that is unique to a given user. It is used by third parties to group together registration IDs for a single user. Note that <code>notification_key_name</code> and <code>notification_key</code> are unique to a group of registration IDs. It is also @@ -116,10 +108,109 @@ to use in subsequent operations:</p> "registration_ids": ["4", "8", "15", "16", "23", "42"] }</pre> +<h3 id="request-server">Request format</h3> + +<p>To send a message in cases where your notification key is generated on the server, +the application server issues a POST request to +<code>https://android.googleapis.com/gcm/notification</code>.</p> + +<p>Here is the HTTP request header you should use for all server side create/add/remove operations:</p> + +<pre>content-type: "application/json" +Header : "project_id": <projectID> +Header: "Authorization", "key=API_KEY" +</pre> + + +<h2 id="gen-client">Generate a Notification Key on the Client</h2> + +<p>Generating a notification key on the client is useful for cases where a server is unavailable. +To generate a notification key on the client, the device must have at least one +Google account. Note that the process for generating a notification key on the client is significantly +different from the server process described above.</p> + +<p>To generate a notification key on the client:</p> + +<ol> + <li>Open your project in the <a href="https://cloud.google.com/console">Google Developers Console</a>.</li> + <li>Click <strong>APIS & AUTH > Credentials</strong>.</li> + <li>Under OAuth, click <strong>Create new Client ID</strong>.</li> + <li>In the <strong>Create Client ID</strong> dialog, select <strong>Web Application</strong> as +the application type, and click <strong>Create Client ID</strong>.</li> + <li>Copy the value from <strong>Client ID for web application > Client ID</strong>. +This client ID represents a Google account "scope" that you will use to generate an {@code id_token}.</li> +</ol> + +<p>Once you've followed the above steps and gotten a client ID from Google Developers Console, + you're ready to add this feature to your app. First check the device for the presence of a Google +account. For example:</p> + +<pre>// This snippet takes the simple approach of using the first returned Google account, +// but you can pick any Google account on the device. +public String getAccount() { + Account[] accounts = AccountManager.get(getActivity()). + getAccountsByType("com.google"); + if (accounts.length == 0) { + return null; + } + return accounts[0].name; +}</pre> + +<p>Next, get an authentication token ({@code id_token}) by using the <code><a href= +"http://developer.android.com/reference/com/google/android/gms/auth/GoogleAuthUtil.html">GoogleAuthUtil</a></code> +class. For example:</p> + +<pre>String accountName = getAccount(); + +// Initialize the scope using the client ID you got from the Console. +final String scope = "audience:server:client_id:" + + "1262xxx48712-9qs6n32447mcj9dirtnkyrejt82saa52.apps.googleusercontent.com"; +String id_token = null; +try { + id_token = GoogleAuthUtil.getToken(context, accountName, scope); +} catch (Exception e) { + log("exception while getting id_token: " + e); +} +...</pre> + +<p>Now use <code>id_token</code> to authenticate your request. +This add operation returns a {@code notification_key}. +Third parties must save this {@code notification_key} (as well as its mapping to the +<code>notification_key_name</code>) +to use in subsequent operations. Note that a client request only takes a single regID. +The only operations supported on the client side are add/remove.</p> + +<pre>request: +{ + "operation": "add", + "notification_key_name": "appUser-Chris", + "registration_ids": ["4"] + "id_token": "id_token" +}</pre> + +<h3 id="request-client">Request format</h3> + +<p>To send a message in cases where your notification key is generated on the client, +the application server issues a POST request to +<code>https://android.googleapis.com/gcm/googlenotification</code>.</p> + +<p>Here is the HTTP request header you should use for all add/remove operations. The +client side doesn't support the create operation; +the add operation has the effect of creating the notification key if it doesn't already +exist:</p> + +<pre>content-type: "application/json" +Header : "project_id": <projectID> +</pre> + +<p>Note that the authentication token is passed in the JSON body as shown above, not the header. +This is different from the server case.</p> + + <h2 id="add">Add Registration IDs</h2> <p>This example shows how to add registration IDs for a given notification key. -The maximum number of members allowed for a {@code notification_key} is 10.</p> +The maximum number of members allowed for a {@code notification_key} is 20.</p> <p>Note that the <code>notification_key_name</code> is not strictly required for adding/removing regIDs. But including it protects you against accidentally using diff --git a/docs/html/google/gcm/server.jd b/docs/html/google/gcm/server.jd index ccd1267..e3a6b25 100644 --- a/docs/html/google/gcm/server.jd +++ b/docs/html/google/gcm/server.jd @@ -120,7 +120,8 @@ have an application server that meets the following criteria:</p> <li>Able to store the API key and client registration IDs. The API key is included in the header of POST requests that send messages.</li> - <li>Able to generate message IDs to uniquely identify each message it sends.</li> + <li>Able to generate message IDs to uniquely identify each message it sends. Message IDs +should be unique per sender ID.</li> </ul> <h2 id="send-msg">Sending Messages</h2> diff --git a/docs/html/google/gcs/gcs-signup.jd b/docs/html/google/gcs/gcs-signup.jd new file mode 100644 index 0000000..7334cec --- /dev/null +++ b/docs/html/google/gcs/gcs-signup.jd @@ -0,0 +1,10 @@ +page.title=Sign Up for Google Cloud Save + +@jd:body + +<p>Sign up to be a trial partner for Google Cloud Save.</p> + + +<iframe src="https://docs.google.com/a/google.com/forms/d/1_V67YIXzLDLb-UzxOOpSjUDuJFfeYg3hEUT0oliK2ck/viewform?embedded=true" width="100%" height="930" frameborder="0" marginheight="0" marginwidth="0" id="signupform">Loading...</iframe> +</body> +</html> diff --git a/docs/html/google/gcs/index.jd b/docs/html/google/gcs/index.jd new file mode 100644 index 0000000..e5f4776 --- /dev/null +++ b/docs/html/google/gcs/index.jd @@ -0,0 +1,30 @@ +page.title=Google Cloud Save +page.tags="gcs" +header.hide=1 +@jd:body + + +<div class="landing-banner"> + +<div class="col-5" style="min-height:100px"> + <img src="{@docRoot}images/google/gcs.png" /> +</div> +<div class="col-7"> + + <h1 itemprop="name" style="margin-bottom:0;">Google Cloud Save</h1> + <p itemprop="description"> + Google Cloud Save is a service that enables per-user data storage +and sync in your apps with no backend programming required. Google Cloud Save +stores its data +in <a href="http://developers.google.com/datastore/">Google Cloud Datastore</a>, + a fully managed, schemaless database for storing non-relational data. Cloud +Datastore automatically scales with your users. +Google Cloud Save works even when your device is offline, and it +provides an easy transition to server-side coding because +the same database is accessible via App Engine and Compute Engine. +Finally, Google Cloud Save provides a generous initial per-user free quota that +expands as your user base grows. +</p> +<a href="{@docRoot}google/gcs/gcs-signup.html" class="button">Sign Up</a> +</div> +</div> diff --git a/docs/html/google/index.jd b/docs/html/google/index.jd index 2e97d62..4778a85 100644 --- a/docs/html/google/index.jd +++ b/docs/html/google/index.jd @@ -89,6 +89,16 @@ cloud messaging.</p> to use Google Cloud Messaging.</p> </div> +<div class="landing-cell"> + <div class="cell-icon"> + <img src="{@docRoot}images/google/gcs-small.png" width="40" > + </div> + <h4><a href="{@docRoot}google/gcs/index.html" + >Google Cloud Save</a></h4> + <p>Enable per-user data storage and sync in your apps with no backend programming + required.</p> +</div> + </div><!-- col-6 --> diff --git a/docs/html/images/google/datastore-logo.png b/docs/html/images/google/datastore-logo.png Binary files differnew file mode 100644 index 0000000..a0fc0a0 --- /dev/null +++ b/docs/html/images/google/datastore-logo.png diff --git a/docs/html/images/google/gcs-small.png b/docs/html/images/google/gcs-small.png Binary files differnew file mode 100644 index 0000000..b8dbe0d --- /dev/null +++ b/docs/html/images/google/gcs-small.png diff --git a/docs/html/images/google/gcs.png b/docs/html/images/google/gcs.png Binary files differnew file mode 100644 index 0000000..7355d64 --- /dev/null +++ b/docs/html/images/google/gcs.png diff --git a/docs/html/images/home/auto.png b/docs/html/images/home/auto.png Binary files differindex 233d69d..7ea01b0 100644 --- a/docs/html/images/home/auto.png +++ b/docs/html/images/home/auto.png diff --git a/docs/html/images/home/tv.png b/docs/html/images/home/tv.png Binary files differindex 47bf4b0..3cf2034 100644 --- a/docs/html/images/home/tv.png +++ b/docs/html/images/home/tv.png diff --git a/docs/html/images/home/wear.png b/docs/html/images/home/wear.png Binary files differindex c7a2045..dfaded7 100644 --- a/docs/html/images/home/wear.png +++ b/docs/html/images/home/wear.png diff --git a/docs/html/index.jd b/docs/html/index.jd index c2bf6b6..2f01538 100644 --- a/docs/html/index.jd +++ b/docs/html/index.jd @@ -7,7 +7,7 @@ page.customHeadTag=<meta name="google-site-verification" content="sa-bIAI6GKvct3 @jd:body <!-- Top full-bleed carousel --> -<div class="home-new-carousel-1"> +<div class="home-new-carousel-1" style="margin-top:40px"> <div class="fullscreen-carousel-content"> <div class="vcenter"> <div class="wrap clearfix"> @@ -42,7 +42,7 @@ page.customHeadTag=<meta name="google-site-verification" content="sa-bIAI6GKvct3 </div> <!-- end .fullscreen-carousel-content --> </div> <!-- end .fullscreen-carousel --> -<div class="actions-bar"> +<div class="actions-bar" style="margin-top:30px"> <div class="wrap"> <div class="actions"> <div><a href="{@docRoot}sdk/index.html">Get the SDK</a></div> @@ -68,13 +68,33 @@ page.customHeadTag=<meta name="google-site-verification" content="sa-bIAI6GKvct3 <div class="landing-body" style="margin-top: 80px;"> <div class="landing-breakout cols"> <div class="col-3-wide"> - <a href="{@docRoot}wear/index.html"><img src="{@docRoot}images/home/wear.png"></a> + <img src="{@docRoot}images/home/wear.png"> + <p class="landing-small" style="margin-top:30px"> + Provide information on-the-go for your users, whenever they need it. + </p> + <p class="landing-small"> + <a href="{@docRoot}wear/index.html">Learn about Android Wear</a> + </p> </div> <div class="col-3-wide"> - <a href="{@docRoot}tv/index.html"><img src="{@docRoot}images/home/tv.png"></a> + <img src="{@docRoot}images/home/tv.png"> + <p class="landing-small" style="margin-top:30px"> + Build your apps for the big screen and bring your content to life. + </p> + <p class="landing-small"> + <a href="{@docRoot}tv/index.html">Learn about Android TV</a> + + </p> </div> <div class="col-3-wide"> - <a href="{@docRoot}auto/index.html"><img src="{@docRoot}images/home/auto.png"></a> + <img src="{@docRoot}images/home/auto.png"> + <p class="landing-small" style="margin-top:30px"> + Extend your music apps to automobile + entertainment systems. + </p> + <p class="landing-small"> + <a href="{@docRoot}auto/index.html">Learn about Android Auto</a> + </p> </div> </div> </div> diff --git a/docs/html/jd_tag_helpers.js b/docs/html/jd_tag_helpers.js index b0fe67a..7538e4d 100644 --- a/docs/html/jd_tag_helpers.js +++ b/docs/html/jd_tag_helpers.js @@ -64,6 +64,7 @@ function buildResourceLookupMap(resourceDict) { // Type lookups var ALL_RESOURCES_BY_TYPE = { + 'about': ABOUT_RESOURCES, 'design': DESIGN_RESOURCES, 'distribute': DISTRIBUTE_RESOURCES, 'google': GOOGLE_RESOURCES, @@ -79,6 +80,7 @@ var IS_RESOURCE_OF_TYPE = buildResourceLookupMap(ALL_RESOURCES_BY_TYPE); // Tag lookups var ALL_RESOURCES_BY_TAG = mergeMaps( + {map:ABOUT_BY_TAG,arr:ABOUT_RESOURCES}, {map:DESIGN_BY_TAG,arr:DESIGN_RESOURCES}, {map:DISTRIBUTE_BY_TAG,arr:DISTRIBUTE_RESOURCES}, {map:GOOGLE_BY_TAG,arr:GOOGLE_RESOURCES}, diff --git a/docs/html/preview/api-overview.jd b/docs/html/preview/api-overview.jd index 284ad2a..d9cac48 100644 --- a/docs/html/preview/api-overview.jd +++ b/docs/html/preview/api-overview.jd @@ -18,7 +18,7 @@ sdk.platform.apiLevel=20 <li><a href="#ART">New Android Runtime (ART)</a></li> <li><a href="#BehaviorNotifications">If your app implements notifications...</a></li> <li><a href="#BehaviorMediaControl">If your app uses RemoteControlClient...</a></li> - <li><a href="#BehaviorGetRecentTasks">If your app uses ActivityManager.getRecentTasks()...</a></li> +<li><a href="#BehaviorGetRecentTasks">If your app uses ActivityManager.getRecentTasks()...</a></li> </ol> </li> <li><a href="#UI">User Interface</a> @@ -69,7 +69,7 @@ sdk.platform.apiLevel=20 <li><a href="#Enterprise">Enterprise</a> <ol> <li><a href="#ManagedProvisioning">Managed provisioning</a></li> - <li><a href="#LockToAppMode">Lock-to-App mode</a></li> + <li><a href="#TaskLocking">Task locking</a></li> </ol> </li> <li><a href="#Printing">Printing Framework</a> @@ -163,10 +163,10 @@ Behavior on the Android Runtime (ART)</a>. Pay particular attention if:</p> backgrounds to match the new material design widgets. Make sure that all your notifications look right with the new color scheme:</p> -<div class="figure" style="width:220px"> +<div class="figure" style="width:320px"> <img src="images/hun-example.png" srcset="images/hun-example@2x.png 2x" - alt="" width="220" height="372" id="figure1" /> + alt="" width="320" height="541" id="figure1" /> <p class="img-caption"> <strong>Figure 1.</strong> Fullscreen activity showing a heads-up notification </p> @@ -177,7 +177,7 @@ notifications look right with the new color scheme:</p> <li>Update or remove assets that involve color.</li> <li>The system automatically inverts action icons in notifications. Use - {@code android.app.Notification.Builder.setColor()} to set an accent color + {@code android.app.Notification. Builder.setColor()} to set an accent color in a circle behind your {@link android.app.Notification#icon} image.</li> <li>The system ignores all non-alpha channels in action icons and the main @@ -188,7 +188,9 @@ notifications look right with the new color scheme:</p> <p>If you are currently adding sounds and vibrations to your notifications by using the {@link android.media.Ringtone}, {@link android.media.MediaPlayer}, or {@link android.os.Vibrator} classes, remove this code so that -the system can present notifications correctly in <a href="#DoNotDisturb">Do Not Disturb</a> mode. Instead, use the {@link android.app.Notification.Builder} methods instead to add sounds and vibration.</p> +the system can present notifications correctly in <a href="#DoNotDisturb">Do +Not Disturb</a> mode. Instead, use the {@link android.app.Notification.Builder} +methods instead to add sounds and vibration.</p> <p>Notifications now appear in a small floating window (also called a <em>heads-up notification</em>) when the device is active @@ -218,40 +220,46 @@ gives your app more control over the presentation of media buttons, while providing a consistent experience for users across the lockscreen and unlocked device.</p> -<p>The L Developer Preview introduces a new {@code android.app.Notification.MediaStyle} template which is recommended for this purpose. {@code MediaStyle} converts notification actions that you added with {@link android.app.Notification.Builder#addAction(int, java.lang.CharSequence, android.app.PendingIntent) Notification.Builder.addAction()} into compact buttons embedded in your app's media playback notifications.</p> +<p>The L Developer Preview introduces a new +{@code android.app.Notification.MediaStyle} template which is recommended for +this purpose. {@code MediaStyle} converts notification actions that you added +with +{@link android.app.Notification.Builder#addAction(int, java.lang.CharSequence, + android.app.PendingIntent) +Notification.Builder.addAction()} into compact buttons embedded in your app's +media playback notifications.</p> <p>If you are using the new -{@code android.media.session.MediaSession} class (see <a href="#MediaPlaybackControl">Media Playback Control</a> below), attach your session -token with {@code Notification.MediaStyle.setMediaToken()} to inform the -system that this notification controls an ongoing media session.</p> +{@code android.media.session.MediaSession} class +(see <a href="#MediaPlaybackControl">Media Playback Control</a> below), attach +your session token with {@code Notification.MediaStyle.setMediaToken()} to +inform the system that this notification controls an ongoing media session.</p> <p>Call {@code Notification.Builder.setVisibility(Notification.VISIBILITY_PUBLIC)} to mark a -notification as safe to show atop any lockscreen (secure or otherwise). For more information, see -<a href="#LockscreenNotifications">Lockscreen Notifications</a>.</p> +notification as safe to show atop any lockscreen (secure or otherwise). For more +information, see <a href="#LockscreenNotifications">Lockscreen Notifications</a>.</p> <h3 id="BehaviorGetRecentTasks">If your app uses ActivityManager.getRecentTasks()...</h3> -<p>With the introduction of the new <em>concurrent documents and activities tasks</em> feature in the upcoming -release (see <a href="#Recents">Concurrent documents and activities in Recents -screen</a> below), +<p>With the introduction of the new <em>concurrent documents and activities +tasks</em> feature in the upcoming release (see <a href="#Recents">Concurrent +documents and activities in Recents screen</a> below), the {@link android.app.ActivityManager#getRecentTasks -ActivityManager.getRecentTasks()} method is now -deprecated to improve user privacy. For backward -compatibility, this method still returns a small subset of its data, including the -calling application’s own tasks and possibly some other non-sensitive tasks -(such as Home). If your app is using this method to retrieve its own tasks, -use {@code android.app.ActivityManager.getAppTasks()} instead to retrieve that -information.</p> +ActivityManager.getRecentTasks()} method is now deprecated to improve user +privacy. For backward compatibility, this method still returns a small subset of +its data, including the calling application’s own tasks and possibly some other +non-sensitive tasks (such as Home). If your app is using this method to retrieve +its own tasks, use {@code android.app.ActivityManager.getAppTasks()} instead to +retrieve that information.</p> <h2 id="UI">User Interface</h2> <h3 id="MaterialDesign">Material design support</h3> <p>The upcoming release adds support for Android's new <em>material</em> design -style. You can create -apps with material design that are visually dynamic and have UI element transitions -that feel natural to users. This support includes:</p> +style. You can create apps with material design that are visually dynamic and +have UI element transitions that feel natural to users. This support includes:</p> <ul> @@ -268,9 +276,9 @@ that feel natural to users. This support includes:</p> <a href="{@docRoot}preview/material/index.html">Material Design</a>.</p> <h3 id="LockscreenNotifications">Lockscreen notifications</h3> -<p>Lockscreens in the L Developer Preview have the ability to present notifications. -Users can choose via <em>Settings</em> whether to allow sensitive notification -content to be shown over a secure lockscreen.</p> +<p>Lockscreens in the L Developer Preview have the ability to present +notifications. Users can choose via <em>Settings</em> whether to allow +sensitive notification content to be shown over a secure lockscreen.</p> <p>Your app can control the level of detail visible when its notifications are displayed over the secure lockscreen. To control the visibility level, call @@ -287,8 +295,12 @@ notification’s icon.</li> <p>When {@code VISIBILITY_PRIVATE} is set, you can also provide a redacted version of the notification content that hides personal details. For example, -an SMS app might display a notification that shows "You have 3 new text messages." but hides the message content and senders. To provide this alternative notification, first create the replacement notification using {@link android.app.Notification.Builder}. When you create the private notification object, attach -the replacement notification to it through the {@code Notification.Builder.setPublicVersion()} method.</p> +an SMS app might display a notification that shows "You have 3 new text messages." +but hides the message content and senders. To provide this alternative +notification, first create the replacement notification using +{@link android.app.Notification.Builder}. When you create the private +notification object, attach the replacement notification to it through the +{@code Notification.Builder.setPublicVersion()} method.</p> <h3 id="DoNotDisturb">Do Not Disturb mode</h3> @@ -354,7 +366,8 @@ through the {@code android.app.ActivityManager.AppTask} class.</p> <p>To insert a logical break so that the system treats your activity as a new task, use {@code android.content.Intent.FLAG_ACTIVITY_NEW_DOCUMENT} when -launching the activity with {@link android.app.Activity#startActivity(android.content.Intent) startActivity()}. You can also get this behavior by declaring the +launching the activity with {@link android.app.Activity#startActivity(android.content.Intent) +startActivity()}. You can also get this behavior by declaring the <a href="{@docRoot}guide/topics/manifest/activity-element.html"><activity></a> attribute {@code documentLaunchMode="intoExisting"} or {@code ="always"} in your manifest.</p> @@ -381,7 +394,8 @@ as well as bug fixes. The default user-agent string for a been updated to incorporate 36.0.0.0 as the version number.</p> <p>Additionally, this release brings support for the -<a href="https://dvcs.w3.org/hg/audio/raw-file/tip/webaudio/specification.html">WebAudio</a>, <a href="https://www.khronos.org/webgl/">WebGL</a>, and +<a href="https://dvcs.w3.org/hg/audio/raw-file/tip/webaudio/specification.html">WebAudio</a>, +<a href="https://www.khronos.org/webgl/">WebGL</a>, and <a href="http://www.webrtc.org/">WebRTC</a> open standards. To learn more about the new features included in this release, see <a href="https://developer.chrome.com/multidevice/webview/overview">WebView for Android</a>.</p> @@ -424,8 +438,10 @@ ES 3.1. Key new functionality provided in OpenGL ES 3.1 includes:</p> <li>Backward compatibility with OpenGL ES 2.0 and 3.0 </ul> -<p>The Java interface for OpenGL ES 3.1 on Android is provided with GLES31. When using OpenGL ES 3.1, be sure that you declare it in your manifest file with the -<a href="{@docRoot}guide/topics/manifest/uses-feature-element.html">{@code <uses-feature>}</a> tag and the {@code android:glEsVversion} attribute. For example:</p> +<p>The Java interface for OpenGL ES 3.1 on Android is provided with GLES31. When +using OpenGL ES 3.1, be sure that you declare it in your manifest file with the +<a href="{@docRoot}guide/topics/manifest/uses-feature-element.html">{@code <uses-feature>}</a> +tag and the {@code android:glEsVversion} attribute. For example:</p> <pre> <manifest> @@ -434,7 +450,9 @@ ES 3.1. Key new functionality provided in OpenGL ES 3.1 includes:</p> </manifest> </pre> -<p>For more information about using OpenGL ES, including how to check the device’s supported OpenGL ES version at runtime, see the <a href="{@docRoot}guide/topics/graphics/opengl.html">OpenGL ES API guide</a>.</p> +<p>For more information about using OpenGL ES, including how to check the +device’s supported OpenGL ES version at runtime, see the +<a href="{@docRoot}guide/topics/graphics/opengl.html">OpenGL ES API guide</a>.</p> <h2 id="Multimedia">Multimedia</h2> @@ -462,12 +480,13 @@ capture request. Now when the system completes the image capture request, your <ul> <li>Your app can now supply audio data in floating-point format ({@code android.media.AudioFormat.ENCODING_PCM_FLOAT}). This permits greater -dynamic range, more consistent precision, and greater headroom. Floating-point arithmetic is especially useful during intermediate calculations. Playback +dynamic range, more consistent precision, and greater headroom. Floating-point +arithmetic is especially useful during intermediate calculations. Playback end-points use integer format for audio data, and with lower bit-depth. (In the L Developer Preview, portions of the internal pipeline are not yet floating-point.) - <li>Your app can now supply audio data as a {@link java.nio.ByteBuffer}, in the same -format as provided by {@link android.media.MediaCodec}. + <li>Your app can now supply audio data as a {@link java.nio.ByteBuffer}, in +the same format as provided by {@link android.media.MediaCodec}. <li>The {@code WRITE_NON_BLOCKING} option can simplify buffering and multithreading for some apps. </ul> @@ -501,33 +520,40 @@ knows about your playback and can extract and show album art.</p> <h3 id="DirectorySelection">Directory selection</h3> -<p>The L Developer Preview extends the <a href="{@docRoot}guide/topics/providers/document-provider.html">Storage Access Framework</a> to let users select an entire directory, rather than individual files, to -give your app read/write access to media files. When a directory is selected, -your app also has access to all its child directories and content.</p> - -<p>To get the absolute paths to directories on external storage devices where -applications can store media files, call the new -{@code android.content.Context.getExternalMediaDirs()} method. No -additional -permissions are needed by your app to read or write to the returned paths. -In this context, "external storage devices" are those devices which the system -considers to be a -permanent part of the device, and includes emulated external storage and -physical media slots such as SD cards in battery compartments.</p> - -<p>You can bring up a system UI to allow the user to pick a directory subtree. -To do so, send {@code android.intent.action.OPEN_DOCUMENT_TREE} in an -{@link android.content.Intent}. If the call is successful, the system displays -the {@link android.provider.DocumentsProvider} instances installed on the -device for the user to select. When the user selects a directory from this UI, -the system returns a URI representing the selected directory tree.</p> - -<p>If you want to access a document in an existing directory, call the -{@code android.provider.DocumentsContract.buildDocumentViaUri()} method. -Pass the method a URI representing the path to the parent directory, and the -target document -ID. The method returns a new {@link android.net.Uri} which your app can -use to write media content with {@code DocumentsContract.createDocument()}. +<p>The L Developer Preview extends the <a href="{@docRoot}guide/topics/providers/document-provider.html">Storage Access Framework</a> to let users select an entire directory subtree, +giving apps read/write access to all contained documents without requiring user +confirmation for each item.</p> + +<p>To select a directory subtree, build and send an +{@code android.intent.action.OPEN_DOCUMENT_TREE} {@link android.content.Intent}. +The system displays all +{@link android.provider.DocumentsProvider} instances that support subtree selection, +letting the user browse and select a directory. The returned URI represents access to the selected +subtree. You can then use {@code DocumentsContract.buildChildDocumentsUriUsingTree()} +and {@code DocumentsContract.buildDocumentUriUsingTree()} along with +{@code ContentResolver.query()} to explore the subtree.</p> + +<p>The new {@code DocumentsContract.createDocument()} method lets you create +new documents or directories anywhere under the subtree. To manage +existing documents, use {@code DocumentsContract.renameDocument()} and +{@code DocumentsContract.deleteDocument()}. Check {@code DocumentsContract.Document.COLUMN_FLAGS} +to verify provider support for these calls before issuing them.</p> + +<p>If you're implementing a {@link android.provider.DocumentsProvider} and want +to support subtree selection, implement {@code DocumentsProvider.isChildDocument()} +and include {@code Documents.Contract.FLAG_SUPPORTS_IS_CHILD} in your +{@code Root.COLUMN_FLAGS}.</p> + +<p>The L Developer Preview also introduces new package-specific directories on +shared storage where your app can place media files for inclusion in +{@link android.provider.MediaStore}. The new +{@code android.content.Context.getExternalMediaDirs()} returns paths to these +directories on all shared storage devices. Similarly to +{@link android.content.Context#getExternalFilesDir(java.lang.String) Context.getExternalFilesDir()}, +no additional permissions are needed by your app to access the returned paths. The +platform periodically scans for new media in these directories, but you can also +use {@link android.media.MediaScannerConnection} to explicitly scan for new +content.</p> <h2 id="Wireless">Wireless & Connectivity</h2> @@ -561,7 +587,8 @@ information about the network, or to direct traffic to use the selected network.</p> <h3 id="BluetoothBroadcasting">Bluetooth broadcasting</h3> -<p>Android 4.3 introduced platform support for <a href="{@docRoot}guide/topics/connectivity/bluetooth-le.html">Bluetooth Low Energy</a> +<p>Android 4.3 introduced platform support for + <a href="{@docRoot}guide/topics/connectivity/bluetooth-le.html">Bluetooth Low Energy</a> (BLE) in the central role. In the L Developer Preview, an Android device can now act as a Bluetooth LE <em>peripheral device</em>. Apps can use this capability to make their presence known to @@ -569,7 +596,8 @@ nearby devices. For instance, you can build apps that allow a device to function as a pedometer or health monitor and communicate its data with another BLE device.</p> -<p>The new {@code android.bluetooth.le} APIs enable your apps to broadcast advertisements, scan for responses, and form connections with nearby BLE devices. +<p>The new {@code android.bluetooth.le} APIs enable your apps to broadcast +advertisements, scan for responses, and form connections with nearby BLE devices. You must add the {@code android.permission.BLUETOOTH_ADMIN} permission in your manifest in order for your app to use the new advertising and scanning features.</a> @@ -692,7 +720,7 @@ in {@code <sdk>/tools}.</p> <img src="images/battery_historian.png" srcset="images/battery_historian@2x.png 2x" - alt="" width="440" height="240" + alt="" width="760" height="462" id="figure2" /> <p class="img-caption"> <strong>Figure 2.</strong>HTML visualization generated by the Battery @@ -726,7 +754,7 @@ $ historian.par [-p powerfile] bugreport.txt > out.html <div class="figure" style="width:360px"> <img src="images/managed_apps_launcher.png" srcset="images/managed_apps_launcher@2x.png 2x" - alt="" width="360" height="572" id="figure3" /> + alt="" width="360" height="609" id="figure3" /> <p class="img-caption"> <strong>Figure 3.</strong> Launcher screen showing managed apps (marked with a lock badge) @@ -734,17 +762,10 @@ $ historian.par [-p powerfile] bugreport.txt > out.html </div> <p>The L Developer Preview provides new functionality for running apps within -an enterprise environment:</p> -<ul> -<li><strong>Create managed user profiles</strong>. A device administrator can -initiate a managed provisioning process to add a co-present but separate managed -profile to a device with an existing personal account. The administrator has -control over the managed profile.</li> -<li><strong>Set device owner</strong>. Device administrators can also initiate a -managed provisioning process to automatically provision a -currently-unprovisioned device such that they have full control over the -device.</li> -</ul> +an enterprise environment. A device administrator can +initiate a managed provisioning process to add a co-present but separate <em>managed +profile</em> to a device with an existing personal account. The administrator has +control over the managed profile.</p> <p>To start the managed provisioning process, send {@code ACTION_PROVISION_MANAGED_PROFILE} in an {@link android.content.Intent}. If the @@ -767,47 +788,71 @@ for the current user and any associated managed profiles. Your Launcher can make the managed apps visually prominent by appending a “work” badge to the icon drawable with {@code android.os.UserManager.getBadgeDrawableForUser()}.</p> -<h3 id="LockToAppMode">Lock-to-App mode</h3> -<p>The L Developer Preview introduces a new <em>Lock-to-App</em> mode that +<h3 id="TaskLocking">Task locking</h3> +<p>The L Developer Preview introduces a new task locking API that lets you temporarily restrict users from leaving your app or being interrupted -by notifications. Once your app activates this mode, users will not be able to -see notifications, access other apps, or return to the Home screen, until your +by notifications. This could be used, for example, if you are developing an +education app to support high stakes assessment requirements on Android. +Once your app activates this mode, users will not be able to see +notifications, access other apps, or return to the Home screen, until your app exits the mode.</p> -<p>To prevent unauthorized usage, the device on which you want to activate -this mode must have managed profiles or must be fully controlled by a device administrator (see <a href="#ManagedProvisioning">Managed Provisioning</a> for more information). Furthermore, the device or managed profile owner must -authorize apps to use this mode by calling {@code android.app.admin.DevicePolicyManager.setLockTaskComponents()}.</p> +<p>To prevent unauthorized usage, only authorized apps can activate task locking. +Furthermore, task locking authorization must be granted by a +specially-configured <em>device owner</em> app, through the {@code android.app.admin.DevicePolicyManager.setLockTaskComponents()} method.</p> + +<p>To set up a device owner, follow these steps:</p> +<ol> +<li>Attach a device running an <a href="https://source.android.com/source/building-running.html">Android {@code userdebug} build</a> to your development machine.</li> +<li>Install your device owner app.</li> +<li>Create a {@code device_owner.xml} file and save it to the {@code /data/system} +directory on the device. +<pre> +$ adb root +$ adb shell stop +$ rm /tmp/device_owner.xml +$ echo "<?xml version='1.0' encoding='utf-8' standalone='yes' ?>" +>> /tmp/device_owner.xml +$ echo "&device-owner package=\"<your_device_owner_package>\" +name=\"*<your_organization_name>\" />" >> /tmp/device_owner.xml +$ adb push /tmp/device_owner.xml /data/system/device_owner.xml +$ adb reboot +</pre> +</li> +</ol> -<p>Before activating this mode in your app, verify that your activity is authorized by calling {@code DevicePolicyManager.isLockTaskPermitted()}.</p> +<p>Before using the task locking API in your app, verify that your activity is +authorized by calling {@code DevicePolicyManager.isLockTaskPermitted()}.</p> -<p>To activate <em>Lock-to-App</em> mode, call +<p>To activate task locking, call {@code android.app.Activity.startLockTask()} from your authorized activity.</p> -<p>When <em>Lock-to-App</em> mode is active, the following behavior takes -effect:</p> +<p>When task locking is active, the following behavior takes effect:</p> <ul> -<li>The status bar is blank, and user notifications and status information is hidden.</li> -<li>The Home and Recent Apps button is hidden.</li> +<li>The status bar is blank, and user notifications and status information is +hidden.</li> +<li>The Home and Recent Apps buttons are hidden.</li> <li>Other apps may not launch new activities.</li> <li>The current app may start new activities, as long as doing so does not create new tasks.</li> +<li>The user remains locked on your app until an authorized activity calls +{@code Activity.stopLockTask()}.</li> </ul> -<p>The device will remain in this mode until an authorized activity calls -{@code Activity.stopLockTask()}. - <h2 id="Printing">Printing Framework</h2> <h3 id="PDFRender">Render PDF as bitmap</h3> <p>You can now render PDF document pages into bitmap images for printing by using the new {@code android.graphics.pdf.PdfRenderer} class. You must specify a -{@link android.os.ParcelFileDescriptor} that is seekable (that is, the content can be randomly -accessed) on which the system writes the the printable content. Your app can -obtain a page for rendering with {@code openPage()}, then call {@code render()} -to turn the opened {@code PdfRenderer.Page} into a bitmap. You can also set -additional parameters if you only want to convert a portion of the document into -a bitmap image (for example, to implement <a href="http://en.wikipedia.org/wiki/Tiled_rendering">tiled rendering</a> in order to zoom in on the document).</p> +{@link android.os.ParcelFileDescriptor} that is seekable (that is, the content +can be randomly accessed) on which the system writes the the printable content. +Your app can obtain a page for rendering with {@code openPage()}, then call +{@code render()} to turn the opened {@code PdfRenderer.Page} into a bitmap. You +can also set additional parameters if you only want to convert a portion of the +document into a bitmap image (for example, to implement +<a href="http://en.wikipedia.org/wiki/Tiled_rendering">tiled rendering</a> in +order to zoom in on the document).</p> <h2 id="TestingA11y">Testing & Accessibility </h2> @@ -833,8 +878,7 @@ allows you to use shell based tools such as {@code dumpsys}, {@code am}, can now retrieve detailed information about the properties of windows on the screen that sighted users can interact with. To retrieve a list of {@code android.view.accessibility.AccessibilityWindowInfo} objects -representing the -windows information, call the new +representing the windows information, call the new {@code android.accessibilityservice.AccessibilityService.getWindows()} method. <li>You can use the new {@code android.view.accessibility.AccessibilityNodeInfo.AccessibilityAction} to define standard or customized actions to perform on an {@link android.view.accessibility.AccessibilityNodeInfo}. @@ -845,13 +889,16 @@ previously found in {@code AccessibilityNodeInfo}. <h2 id="Manifest">Manifest Declarations</h2> <h3 id="ManifestFeatures">Declarable required features</h3> -<p>The following values are now supported in the <a href="{@docRoot}guide/topics/manifest/uses-feature-element.html">{@code <uses-feature>}</a> element, so you -can ensure that your app is installed only on devices that provide the features +<p>The following values are now supported in the +<a href="{@docRoot}guide/topics/manifest/uses-feature-element.html">{@code <uses-feature>}</a> +element, so you can ensure that your app is installed only on devices that provide the features your app needs.</p> <ul> <li>{@code FEATURE_LEANBACK}. Declares that your app must be installed only on -devices that support the <a href="{@docRoot}training/tv/index.html}">Android TV</a>user interface. Example: +devices that support the +<a href="{@docRoot}training/tv/index.html}">Android TV</a> user interface. +Example: <pre> <uses-feature android:name="android.software.leanback" android:required="true" /> @@ -866,7 +913,9 @@ devices that fully implement the {@code android.webkit.*} APIs. Example: </ul> <h3 id="ManifestPermissions">User permissions</h3> -<p>The following values are now supported in the <a href="{@docRoot}guide/topics/manifest/uses-permission-element.html">{@code <uses-permission>}</a> to declare the +<p>The following values are now supported in the +<a href="{@docRoot}guide/topics/manifest/uses-permission-element.html">{@code + <uses-permission>}</a> to declare the permissions your app requires in order to access certain APIs. <ul> diff --git a/docs/html/preview/images/battery_historian.png b/docs/html/preview/images/battery_historian.png Binary files differindex 5b0db74..f1d4e40 100644 --- a/docs/html/preview/images/battery_historian.png +++ b/docs/html/preview/images/battery_historian.png diff --git a/docs/html/preview/images/battery_historian@2x.png b/docs/html/preview/images/battery_historian@2x.png Binary files differindex dbb5d5e..8c8a87f 100644 --- a/docs/html/preview/images/battery_historian@2x.png +++ b/docs/html/preview/images/battery_historian@2x.png diff --git a/docs/html/preview/images/hun-example.png b/docs/html/preview/images/hun-example.png Binary files differindex 9613a92..251b938 100644 --- a/docs/html/preview/images/hun-example.png +++ b/docs/html/preview/images/hun-example.png diff --git a/docs/html/preview/images/hun-example@2x.png b/docs/html/preview/images/hun-example@2x.png Binary files differindex 3cb8f5b..5b98a36 100644 --- a/docs/html/preview/images/hun-example@2x.png +++ b/docs/html/preview/images/hun-example@2x.png diff --git a/docs/html/preview/images/managed_apps_launcher.png b/docs/html/preview/images/managed_apps_launcher.png Binary files differindex 983d904..b5ef407 100644 --- a/docs/html/preview/images/managed_apps_launcher.png +++ b/docs/html/preview/images/managed_apps_launcher.png diff --git a/docs/html/preview/images/managed_apps_launcher@2x.png b/docs/html/preview/images/managed_apps_launcher@2x.png Binary files differindex d298fd2..90d7d51 100644 --- a/docs/html/preview/images/managed_apps_launcher@2x.png +++ b/docs/html/preview/images/managed_apps_launcher@2x.png diff --git a/docs/html/preview/index.html b/docs/html/preview/index.html index ff4572b..e657415 100644 --- a/docs/html/preview/index.html +++ b/docs/html/preview/index.html @@ -241,7 +241,7 @@ href="//fonts.googleapis.com/css?family=Roboto+Condensed"> Let us know when you encounter problems, so we can fix them and make the platform better for you and your users. </p><p class="landing-small"> - <a target="_blank" href="https://code.google.com/p/android-developer-preview/"> + <a href="https://code.google.com/p/android-developer-preview/"> Report Issues</a> </p> <p></p> @@ -257,7 +257,7 @@ href="//fonts.googleapis.com/css?family=Roboto+Condensed"> Join the community of Android developers testing out the L Developer Preview and share your thoughts and experiences. </p><p class="landing-small"> - <a target="_blank" href="https://plus.sandbox.google.com/communities/113159138894928487684"> + <a href="https://plus.sandbox.google.com/communities/113159138894928487684"> Discuss on Google+</a> </p> </div> @@ -274,7 +274,7 @@ href="//fonts.googleapis.com/css?family=Roboto+Condensed"> for news about the changes. </p> <p class="landing-small"> - <a target="_blank" href="/preview/support.html">Get Support</a> + <a href="/preview/support.html">Get Support</a> </p> </div> </div> diff --git a/docs/html/preview/setup-sdk.jd b/docs/html/preview/setup-sdk.jd index 66262dc..78003f5 100644 --- a/docs/html/preview/setup-sdk.jd +++ b/docs/html/preview/setup-sdk.jd @@ -7,7 +7,7 @@ as using the Android SDK Manager and creating projects. If you're new to Android, see <a href="/training/basics/firstapp/index.html">Building Your First App</a> training lesson first.</a></p> -<h2>Download the SDK</h2> +<h2 id="downloadSdk">Download the SDK</h2> <ol> <li>Start the Android SDK Manager.</li> @@ -20,7 +20,7 @@ App</a> training lesson first.</a></p> <b>Install</b>.</li> </ol> -<h2>Set Up Hardware and AVDs</h2> +<h2 id="setupHardware">Set Up Hardware and AVDs</h2> <p>The Android L developer preview provides you with 32-bit system images to flash the following devices: @@ -35,10 +35,9 @@ to flash the following devices: experimental 64-bit system images along with standard 32-bit system images. </p> -<h3>Instal the L Preview System Image</h3> +<h3 id="installImage">Install the L Preview System Image</h3> -<!-- Will we get an official warning text from the lawyercats? Is this it? --> -<p class="warning"><b>Warning</b>: This is a preview version of the Android +<p class="warning"><b>Warning:</b> This is a preview version of the Android system image, and is subject to change. Your use of this system image is governed by the Android SDK Preview License Agreement. The Android preview system image is not a stable release, and may contain errors and defects that @@ -49,35 +48,37 @@ can cause your phone and installed services and applications to stop working. <ol> - <li>Download and extract the Android Developer Preview package to a directory - (which we'll call <code><l_download_dir></code> in these - instructions).</li> - <li>Connect your powered-off Android device to your development machine. Put - the device in fastboot mode by pressing and holding the following buttons: - <ul> - <li><strong>Nexus 5:</strong> <i>volume down</i> + <i>volume up</i> + - <i>power</i></li> - <li><strong>Nexus 7:</strong> <i>volume down</i> + <i>power</i> </li> - </ul> - <p class="note">Alternatively, you can enter fastboot mode by booting up - the device and running <code>adb reboot bootloader</code> with USB debugging - turned on.</p> + <li>Download and uncompress the Android Developer Preview package. + <p class="table-caption" id="table1"> + <strong>Table 1.</strong> L Developer Preview system images.</p> + <table> + <tr> + <th scope="col">Device</th> + <th scope="col">Download</th> + <th scope="col">MD5 Checksum</th> + <th scope="col">SHA-1 Checksum</th> + </tr> + <tr id="hammerhead"> + <td>Nexus 5 (GSM/LTE) "hammerhead"</td> + <td><!-- TODO --></td> + <td><code>5a6ae77217978cb7b958a240c2e80b57</code></td> + <td><code>ac1d8a8e4f4a1dca5864dc733caa940bffc28616</code></td> + </tr> + <tr id="razor"> + <td>Nexus 7 (Wifi) "razor"</td> + <td><!-- TODO --></td> + <td><code>b293a5d3a4e07beabebcc0be85ad68a2</code></td> + <td><code>d0ddf8ce733ba2a34279cdff8827fd604762c2342d</code></td> + </tr> + </table> </li> + <li>Follow the instructions at <a href="https://developers.google.com/android/nexus/images#instructions">developers.google.com/android</a> - to set up your system for flashing devices.</li> - <li>Run the <code><l_download_dir>/flash-all</code> script - corresponding to your platform. This script flashes all of the system data - onto the phone.</li> <!-- Confirm names of flash scripts --> - <li>(Optional) After flashing is complete, lock your device's bootloader by - putting it in fastboot mode and running <code>fastboot oem lock</code>. - (This does not wipe your device.) Once you do this, you will not be able to - flash your device until you run run <code>fastboot oem unlock</code>, - which unlocks the bootloader and wipes your device. We recommend you leave the - bootloader unlocked until you are done with flashing the device.</li> + to flash the image onto your device.</li> </ol> -<h3>Revert a Device to Factory Specifications</h3> +<h3 id="revertDevice">Revert a Device to Factory Specifications</h3> <p>If you want to uninstall the L Preview and revert the device to factory specifications, go to <a href="http://developers.google.com/android @@ -85,8 +86,7 @@ specifications, go to <a href="http://developers.google.com/android to flash to for your device. Follow the instructions on that page to flash the image to your device.</p> - -<h3>Set up an AVD</h3> +<h3 id="setupAVD">Set up an AVD</h3> <p>You can set up <a href="{@docRoot}tools/devices/">Android Virtual Devices (AVD)</a> and use the emulator to build and test apps with the L Preview.</p> @@ -109,7 +109,7 @@ image to your device.</p> </li> </ol> -<h2>Create a Project</h2> +<h2 id="createProject">Create a Project</h2> <ol> <li>Create a new Android project with the following properties: diff --git a/docs/html/training/app-indexing/index.jd b/docs/html/training/app-indexing/index.jd index cb4135f..7e7241b 100644 --- a/docs/html/training/app-indexing/index.jd +++ b/docs/html/training/app-indexing/index.jd @@ -59,14 +59,6 @@ in your app by adding intent filters in your app manifest.</li> </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> diff --git a/docs/html/wear/index.jd b/docs/html/wear/index.jd index 1de09ee..829f73e 100644 --- a/docs/html/wear/index.jd +++ b/docs/html/wear/index.jd @@ -84,9 +84,8 @@ page.type=about <div class="landing-breakout cols"> <div class="col-3-wide"> - <div class="landing-inset-video-container"> - <img class="landing-bezel-only" src="{@docRoot}wear/images/screens/bezel.png" alt=""> - <img class="gif" src="{@docRoot}wear/images/screens/reservation_animated.gif"> + <div class="framed-wear-square" + <img src="{@docRoot}wear/images/screens/reservation_animated.gif"> </div> <p class="landing-small"> |
