diff options
Diffstat (limited to 'docs/html/training/auto')
| -rw-r--r-- | docs/html/training/auto/audio/index.jd | 476 | ||||
| -rw-r--r-- | docs/html/training/auto/index.jd | 9 | ||||
| -rw-r--r-- | docs/html/training/auto/messaging/index.jd | 533 | ||||
| -rw-r--r-- | docs/html/training/auto/start/index.jd | 210 |
4 files changed, 1228 insertions, 0 deletions
diff --git a/docs/html/training/auto/audio/index.jd b/docs/html/training/auto/audio/index.jd new file mode 100644 index 0000000..2656b96 --- /dev/null +++ b/docs/html/training/auto/audio/index.jd @@ -0,0 +1,476 @@ +page.title=Providing Audio Playback for Auto +page.tags="auto", "car", "automotive", "audio" +page.article=true + +@jd:body + +<div id="tb-wrapper"> +<div id="tb"> + <h2>Dependencies and Prerequisites</h2> + <ul> + <li>Android 5.0 (API level 21) or higher</li> + </ul> + + <h2>This class teaches you how to</h2> + + <ol> + <li><a href="#overview">Provide Audio Services</a></li> + <li><a href="#config_manifest">Configure Your Manifest</a></li> + <li><a href="#implement_browser">Build a Browser Service</a></li> + <li><a href="#implement_callback">Implement Play Controls</a></li> + </ol> + + <h2>Related Samples</h2> + + <ul> + <li><a href="{@docRoot}samples/MediaBrowserService/index.html"> + MediaBrowserService</a></li> + </ul> + + <h2>See Also</h2> + + <ul> + <li> + <a href="{@docRoot}shareables/auto/AndroidAuto-media-apps.pdf"> + User Experience Guidelines: Media Apps</a> + </li> + <li><a href="{@docRoot}training/managing-audio/index.html">Managing Audio + Playback</a></li> + <li><a href="{@docRoot}guide/topics/media/exoplayer.html">ExoPlayer</a> + </li> + </ul> + +</div> +</div> + +<a class="notice-developers-video wide" +href="https://www.youtube.com/watch?v=Q96Sw6v4ULg"> +<div> + <h3>Video</h3> + <p>Devbytes: Android Auto Audio</p> +</div> +</a> + +<p> + Drivers want to access their music and other audio content on the road. Audio books, podcasts, + sports commentary, and recorded talks can make a long trip educational, inspirational, and + enjoyable. The Android framework allows you to extend your audio app so users can listen to their + favorite tunes and audio content using a simpler, safer user interface. +</p> + +<p> + Apps running on mobile devices with Android 5.0 or higher can provide audio services for + dashboard systems running Android Auto. By configuring your app with a few settings and + implementing a service for accessing music tracks, you can enable Auto devices to discover your + app and provide a browse and playback interface for your app's audio content. +</p> + +<p> + This class assumes that you have built an app that plays audio through an Android device's + integrated speakers or connected headphones. It describes how to extend your app to allow Auto + devices to browse your content listings and play it through a car stereo system. +</p> + + +<h2 id="overview">Provide Audio Services</h2> + +<p> + Audio apps do not directly control a car dashboard device that runs Android Auto. When the user + connects an Android mobile device into a dashboard system, Android Auto discovers your app through + manifest entries that indicate what audio services your app can provide. The dashboard system + displays a launcher icon for your app as a music provider and the user can choose to use your + app's services. If the user launches your app, the Auto device queries your app to see what + content is available, displays your content items to the user, and sends requests to your app to + control playback with actions such as play, pause, or skip track. +</p> + +<p>To enable your app to provide audio content for Auto devices, you need to: +</p> + +<ul> + <li>Configure your app manifest to do the following:</li> + <ul> + <li>Declare that your app can provide audio content for Auto devices.</li> + <li>Define a service that provides a browsable list of your audio tracks.</li> + </ul> + </li> + <li>Build a service that provides audio track listing information extending + {@link android.service.media.MediaBrowserService}.</li> + <li>Register a {@link android.media.session.MediaSession} object and implement the + {@link android.media.session.MediaSession.Callback} object to enable playback controls.</li> +</ul> + + +<h2 id="config_manifest">Configure Your Manifest</h2> + +<p> + When a user plugs an Android mobile device into a dashboard device running Auto, the system + requests a list of installed apps that include <a href= + "{@docRoot}guide/topics/manifest/manifest-intro.html">app manifest</a> entries to indicate they + support services for Auto devices and how to access them. This section describes how to configure + your app manifest to indicate your app supports audio services for Auto devices, and allow + dashboard system to connect with your app. +</p> + + +<h3 id="manifest-car-app">Declare Auto audio support</h3> + +<p> + You indicate that your app supports cars capabilities using the following manifest entry: +</p> + +<pre> +<application> + ... + <meta-data android:name="com.google.android.gms.car.application" + android:resource="@xml/automotive_app_desc"/> + ... +<application> +</pre> + +<p> + This manifest entry refers to a secondary XML file, where you declare what Auto capabilities your + app supports. For an app that supports audio for cars, add an XML file to the {@code res/xml/} + resources directory as {@code automotive_app_desc.xml}, with the following content: +</p> + +<pre> +<automotiveApp> + <uses name="media"/> +</automotiveApp> +</pre> + +<p> + For more information about declaring capabilities for Auto devices, see <a href= + "{@docRoot}training/auto/start/index.html#auto-metadata">Getting Started with Auto</a>. +</p> + + +<h3 id="manifest-service">Declare your media browser service</h3> + +<p> + Auto devices expect to connect to a service in order to browse audio track + listings. You declare this service in your manifest to allow the dashboard system to discover + this service and connect to your app. +</p> + +<p>The following code example shows how to declare this listing browser service in your manifest:</p> + +<pre> +<application> + ... + <service android:name="<em>.MyMediaBrowserService</em>" + android:exported="true"> + <intent-filter> + <strong><action android:name=</strong> + <strong>"android.media.browse.MediaBrowserService"/></strong> + </intent-filter> + </service> + ... +<application> +</pre> + +<p> + The service your app provides for browsing audio tracks must extend the + {@link android.service.media.MediaBrowserService}. The implementation of this service is discussed + in the <a href="#implement_browser">Build a Browser Service</a> section. +</p> + +<p class="note"> + <strong>Note:</strong> Other clients can also contact your app's browser service aside from Auto + devices. These media clients might be other apps on a user's mobile device, or they might be other + remote clients. +</p> + +<h3 id="manifest-icon">Specify a notification icon</h3> + +<p> + The Auto user interface shows notifications about your audio app to the user during the course + of operation. For example, if the user has a navigation app running, and one song finishes + and a new song starts, the Auto device shows the user a notification to indicate the change with + an icon from your app. You can specify an icon that is used to represent your app for these + notifications using the following manifest declaration: +</p> + +<pre> +<application> + ... + <meta-data android:name="com.google.android.gms.car.notification.SmallIcon" + android:resource="@drawable/ic_notification" /> + ... +<application> +</pre> + +<p class="note"><strong>Note:</strong> The icon you provide should have transparency enabled, so the +icon's background gets filled in with the app's primary color.</p> + + +<h2 id="implement_browser">Build a Browser Service</h2> + +<p>Auto devices interact with your app by contacting its implementation of a + {@link android.service.media.MediaBrowserService}, which +you declare in your app manifest. This service allows Auto devices to find out what content your app +provides. Connected Auto devices can also query your app's media browser service to contact the +{@link android.media.session.MediaSession} provided by your app, which handles content playback +commands.</p> + +<p>You create a media browser service by extending the +{@link android.service.media.MediaBrowserService} class. +Connected Auto devices can contact your service to do the following:</p> + +<ul> + <li>Browse your app's content hierarchy, in order to present a menu to the + user</li> + <li>Get the token for your app's {@link android.media.session.MediaSession} + object, in order to control audio playback</li> +</ul> + + +<h3 id="browser_workflow">Media browser service workflow</h3> + +<ol> + +<li>When your app's audio services are requested by a user through a connected Auto device, the +dashboard system contacts your app's media browser service. +In your implementation of the {@link android.service.media.MediaBrowserService#onCreate() +onCreate()} method, you must create and register a {@link +android.media.session.MediaSession} object and its callback object.</li> + +<li>The Auto device calls the browser service's {@link +android.service.media.MediaBrowserService#onGetRoot onGetRoot()} method to get the top node of +your content hierarchy. The node retrieved by this call is not used as a menu item, it is only used +to retrieve its child nodes, which are subsequently displayed as the top menu items. +</li> + +<li>Auto invokes the {@link android.service.media.MediaBrowserService#onLoadChildren +onLoadChildren()} method to get the children of the root node, and uses this information to +present a menu to the user.</li> + +<li>If the user selects a submenu, Auto invokes +{@link android.service.media.MediaBrowserService#onLoadChildren +onLoadChildren()} again to retrieve the child nodes of the selected menu item.</li> + +<li>If the user begins playback, Auto invokes the appropriate media session +callback method to perform that action. For more information, see the section about how to +<a href="#implement_callback">Implement Playback Controls</a>. </li> + +</ol> + + +<h3 id="build_hierarchy">Building your content hierarchy</h3> + +<p>Auto devices acting as audio clients call your app's {@link +android.service.media.MediaBrowserService} to find out what content you have +available. You need to implement two methods in your browser service to support +this: {@link android.service.media.MediaBrowserService#onGetRoot +onGetRoot()} and {@link +android.service.media.MediaBrowserService#onLoadChildren +onLoadChildren()}.</p> + +<p>Each node in your content hierarchy is represented by a {@link +android.media.browse.MediaBrowser.MediaItem} object. Each of these objects is +identified by a unique ID string. The client treats these ID strings as +opaque tokens. When a client wants to browse to a submenu, or play a content +item, it passes the ID token. Your app is responsible for associating the ID +token with the appropriate menu node or content item.</p> + +<p class="note"><strong>Note:</strong> You should consider providing different content +hierarchies depending on what client is making the query. In particular, Auto +applications have strict limits on how large a menu they can display. This is +intended to prevent distracting the driver, and to make it easy for the driver +to operate the app via voice commands. For more information on the Auto user +experience restrictions, see the <a href="{@docRoot}shareables/auto/AndroidAuto-media-apps.pdf"> +Auto Media Apps</a> guidelines.</p> + +<p>Your implementation of {@link android.service.media.MediaBrowserService#onGetRoot +onGetRoot()} returns information about the root node of the menu +hierarchy. This root node is the parent of the top items your browse hierarchy. +The method is passed information about the calling client. You can use this +information to decide if the client should have access to your content at all. +For example, if you want to limit your app's content to a list of approved +clients, you can compare the passed {@code clientPackageName} to your whitelist. +If the caller isn't an approved package, you can return null to deny access to +your content.</p> + +<p>A typical implementation of {@link +android.service.media.MediaBrowserService#onGetRoot onGetRoot()} might +look like this:</p> + +<pre> +@Override +public BrowserRoot onGetRoot(String clientPackageName, int clientUid, + Bundle rootHints) { + + // Check the calling client to make sure it's one you approve. + // For example, to limit access to just Auto, the Auto emulator, + // and this app: + + if (!clientPackageName.equals("com.google.android.projection.gearhead") && + !clientPackageName.equals("com.example.android.media") && + !clientPackageName.equals(getApplication().getPackageName()) { + + // If the request comes from an untrusted package, return null. + // No further calls will be made to other media browsing methods. + return null; + } + + // Return a BrowserRoot. If you wish, you could have multiple BrowserRoot + // objects and return different ones depending on the calling client. + // In this example, there's just a single BrowserRoot. + return new BrowserRoot(MEDIA_BROWSER_ROOT, null); + } +</pre> + +<p> + The Auto device client builds the top-level menu by calling {@link + android.service.media.MediaBrowserService#onLoadChildren onLoadChildren()} with the root node + object and getting it's children. The client builds submenus by calling the same method with + other child nodes. The following example code shows a simple implementation of {@link + android.service.media.MediaBrowserService#onLoadChildren onLoadChildren()} method: +</p> + +<pre> +@Override +public void onLoadChildren(final String parentMediaId, + final Result<List<MediaItem>> result) { + + // Assume for example that the music catalog is already loaded/cached. + + List<MediaBrowser.MediaItem> mediaItems = new ArrayList<>(); + + // Check if this is the root menu: + if (MEDIA_BROWSER_ROOT.equals(parentMediaId)) { + + // build the MediaItem objects for the top level, + // and put them in the <result> list + } else { + + // examine the passed parentMediaId to see which submenu we're at, + // and put the children of that menu in the <result> list + } +} +</pre> + + +<h2 id="implement_callback">Enable Playback Control</h2> + +<p> + Auto devices use {@link android.media.session.MediaSession} objects to pass playback control + commands to an app that is providing audio services. Your audio app must create an instance of + this object to pass to the dashboard device and implement callback methods to enable remote + control of audio playback. +</p> + +<h3 id="registering_mediasession">Register a media session</h3> + +<p>An Auto device using your app as audio service needs to obtain a {@link +android.media.session.MediaSession} object from your app. The Auto device uses the session object +to send playback commands requested by the Auto user back to your app.</p> + +<p>When you initialize your browser service, you register that session object with your {@link +android.service.media.MediaBrowserService} by calling the {@link +android.service.media.MediaBrowserService#setSessionToken setSessionToken()} method. This step +allows clients such as an Auto device to retrieve that object by calling your browser service's +{@link android.service.media.MediaBrowserService#getSessionToken getSessionToken()} method.</p> + +<p>In your browser service's {@link +android.service.media.MediaBrowserService#onCreate() onCreate()} method, +create a {@link android.media.session.MediaSession}. You can then query +the {@link android.media.session.MediaSession} to get its token, and register +the token with your browser service:</p> + +<pre> +public void onCreate() { + super.onCreate(); + + ... + // Start a new MediaSession + MediaSession mSession = new MediaSession(this, "session tag"); + setSessionToken(mSession.getSessionToken()); + + // Set a callback object to handle play control requests, which + // implements MediaSession.Callback + mSession.setCallback(new MyMediaSessionCallback()); + + ... +</pre> + +<p> + When you create the media session object, you set a callback object that is used to handle + playback control requests. You create this callback object by providing an implementation of the + {@link android.media.session.MediaSession.Callback} class for your app. The next section + discusses how to implement this object. +</p> + + +<h3 id="playback-commands">Implement play commands</h3> + +<p>When an Auto device requests playback of an audio track from your app, it uses the +{@link android.media.session.MediaSession.Callback} class from your app's +{@link android.media.session.MediaSession} object, which it obtained from your app's +media browse service. When an Auto user wants to play content or control content playback, +such as pausing play or skipping to the next track, Auto invokes one +of the callback object's methods.</p> + +<p>To handle content playback, your app must extend the abstract {@link +android.media.session.MediaSession.Callback} class and implement the methods +that your app supports. The most important callback methods are as follows:</p> + +<dl> + +<dt>{@link android.media.session.MediaSession.Callback#onPlay onPlay()}</dt> +<dd>Invoked if the user chooses play without choosing a specific item. Your +app should play its default content. If playback was paused with +{@link android.media.session.MediaSession.Callback#onPause onPause()}, your +app should resume playback.</dd> + +<dt>{@link android.media.session.MediaSession.Callback#onPlayFromMediaId +onPlayFromMediaId()}</dt> +<dd>Invoked when the user chooses to play a specific item. The method is passed +the item's media ID, which you assigned to the item in the content +hierarchy.</dd> + +<dt>{@link android.media.session.MediaSession.Callback#onPlayFromSearch +onPlayFromSearch()}</dt> +<dd>Invoked when the user chooses to play from a search query. The app should +make an appropriate choice based on the passed search string.</dd> + +<dt>{@link android.media.session.MediaSession.Callback#onPause onPause()}</dt> +<dd>Pause playback.</dd> + +<dt>{@link android.media.session.MediaSession.Callback#onSkipToNext +onSkipToNext()}</dt> +<dd>Skip to the next item.</dd> + +<dt>{@link android.media.session.MediaSession.Callback#onSkipToPrevious +onSkipToPrevious()}</dt> +<dd>Skip to the previous item.</dd> + +<dt>{@link android.media.session.MediaSession.Callback#onStop onStop()}</dt> +<dd>Stop playback.</dd> + +</dl> + +<p>Your app should override these methods to provide any desired functionality. +In some cases you might not implement a method if it is not supported by your app. +For example, if your app plays a live stream (such as a sports +broadcast), the skip to next function might not make sense. In that case, you +could simply use the default implementation of +{@link android.media.session.MediaSession.Callback#onSkipToNext +onSkipToNext()}.</p> + +<p>When your app receives a request to play content, it should play audio the same way it +would in a non-Auto situation (as if the user was listening through a device speaker +or connected headphones). The audio content is automatically sent to the dashboard system +to be played over the car's speakers.</p> + +<p>For more information about playing audio content, see +<a href="{@docRoot}guide/topics/media/mediaplayer.html">Media Playback</a>, +<a href="{@docRoot}training/managing-audio/index.html">Managing Audio Playback</a>, and +<a href="{@docRoot}guide/topics/media/exoplayer.html">ExoPlayer</a>. + + +(for example, by using a {@link +android.media.MediaPlayer} or <a +href="{@docRoot}guide/topics/media/exoplayer.html">ExoPlayer</a>). If the phone +is connected to an Auto device, .</p> diff --git a/docs/html/training/auto/index.jd b/docs/html/training/auto/index.jd new file mode 100644 index 0000000..26eee32 --- /dev/null +++ b/docs/html/training/auto/index.jd @@ -0,0 +1,9 @@ +page.title=Building Apps for Auto +page.trainingcourse=true +page.metaDescription=Starting point for building apps for Auto, with guidelines, information, and examples. +page.image=design/tv/images/focus.png +@jd:body + + + +<p>These classes teach you how to build and extend apps to work with Auto devices.</p>
\ No newline at end of file diff --git a/docs/html/training/auto/messaging/index.jd b/docs/html/training/auto/messaging/index.jd new file mode 100644 index 0000000..c51ad7e --- /dev/null +++ b/docs/html/training/auto/messaging/index.jd @@ -0,0 +1,533 @@ +page.title=Providing Messaging for Auto +page.tags="auto", "car", "automotive", "messaging" +page.article=true + +@jd:body + +<div id="tb-wrapper"> +<div id="tb"> + <h2>Dependencies and Prerequisites</h2> + <ul> + <li>Android 5.0 (API level 21) or higher</li> + </ul> + + <h2>This class teaches you to:</h2> + + <ul> + <li><a href="#overview">Provide Messaging Services</a></li> + <li><a href="#manifest">Configure Your Manifest</a></li> + <li><a href="#support-lib">Import Support Library for Messaging</a></li> + <li><a href="#messaging">Notify Users of Messages</a></li> + <li><a href="#handle_actions">Handle User Actions</a></li> + </ul> + + <h2>Related Samples</h2> + + <ul> + <li><a href="{@docRoot}samples/MessagingService/index.html"> + MessagingService</a></li> + </ul> + + <h2>See Also</h2> + + <ul> + <li><a href="{@docRoot}shareables/auto/AndroidAuto-messaging-apps.pdf"> + User Experience Guidelines: Messaging Apps</a></li> + <li><a href="{@docRoot}guide/topics/ui/notifiers/notifications.html"> + Notifications</a></li> + </ul> +</div> +</div> + +<a class="notice-developers-video wide" + href="https://www.youtube.com/watch?v=gSVLuaOTIPk"> +<div> + <h3>Video</h3> + <p>DevBytes: Android Auto Messaging</p> +</div> +</a> + +<p> + Staying connected through text messages is important to many drivers. Chat apps can let users + know if a child need to be picked up, or if a dinner location has been changed. Apps that provide + sports information might tell the user who just won the big game, and let the user ask questions + about other games being played. The Android framework enables messaging apps to extend their + services into car dashboards using a standard user interface that lets drivers keep their eyes + on the road. +</p> + +<p> + Apps that support messaging can be extended to pass messaging notifications to Auto + dashboard systems, alerting them to new messages and allowing them to respond. You can configure + your messaging app to provide these services when an Android mobile device with your app + installed is connected to an Auto dashboard. Once connected, your app can provide text + information to users and allow them to respond. The Auto dashboard system handles displaying the + notification and the interface for replies. +</p> + +<p> + This lesson assumes that you have built an app that displays messages to the user and receive the + user's replies, such as a chat app. It shows you how to extend your app to hand those messages + off to an Auto device for display and replies. +</p> + + +<h2 id="overview">Provide Messaging Services</h2> + +<p> + Messaging apps do not run directly on the Android dashboard hardware. They are installed on + separate, Android mobile device. When the mobile device is plugged into a dashboard, + the installed messaging apps can offer services for viewing and responding to messages + through the Auto user interface. +</p> + +<p>To enable your app to provide messaging services for Auto devices:</p> + +<ul> + <li>Configure your app manifest to indicate that your app provides messaging services which are + compatible with Android Auto dashboard devices. + </li> + <li>Build and send a specific type of <a href= + "{@docRoot}guide/topics/ui/notifiers/notifications.html">notification</a> for display on Auto + devices. + </li> + <li>Configure your app to receive {@link android.content.Intent} objects that indicate a user + has read or replied to a message. +</ul> + + +<h2 id="#manifest">Configure Your Manifest</h2> + +<p> + You configure your app <a href="{@docRoot}guide/topics/manifest/manifest-intro.html">manifest</a> + to indicate that it supports messaging services for Auto devices and handle message actions. This + section describes what changes to make to your manifest to support messaging for Auto devices. +</p> + + +<h3 id="manifest-messaging">Declare Auto messaging support</h3> + +<p> + When a user connects a Android mobile device to a dashboard running Android, the dashboard + device looks for apps that declare support for vehicle services, such as messaging. You indicate + that your app supports cars capabilities using the following manifest entry: +</p> + +<pre> +<application> + ... + <meta-data android:name="com.google.android.gms.car.application" + android:resource="@xml/automotive_app_desc" /> + ... +<application> +</pre> + +<p> + This manifest entry refers to a secondary xml file, where you declare what Auto capabilities your + app supports. For an app that supports messaging for Auto devices, add an xml file to the {@code + res/xml/} your app's development project directory as {@code automotive_app_desc.xml}, with the + following content: +</p> + +<pre> +<automotiveApp> + <uses name="notification"/> +</automotiveApp> +</pre> + +<p> + For more information about declaring capabilities for Auto devices, see <a href= + "{@docRoot}training/auto/start/index.html#auto-metadata">Getting Started with Auto</a>. +</p> + + +<h3 id="manifest-intent">Define read and reply intent filters</h3> + +<p> + Auto devices use {@link android.content.Intent} objects that indicate a user has read or replied + to a message provided by your app. Your app defines intent types for reading and replying to + messages and adds this information to messaging notifications for Auto devices, so that the + dashboard system can notify your app when a user takes one of these actions. +</p> + +<p> + You define the read action and reply action intents types for your app and the {@code + android.content.BroadcastReceiver} classes that handle them in the manifest. The following code + example demonstrates how to declare these intents and thier associated receivers. +</p> + +<pre> +<application> + ... + <receiver android:name="<em>.MyMessageReadReceiver</em>"> + <intent-filter> + <action android:name="<em>com.myapp.messagingservice.ACTION_MESSAGE_HEARD</em>"/> + </intent-filter> + </receiver> + + <receiver android:name="<em>.MyMessageReplyReceiver</em>"> + <intent-filter> + <action android:name="<em>com.myapp.messagingservice.ACTION_MESSAGE_REPLY</em>"/> + </intent-filter> + </receiver> + ... +</application> +</pre> + +<p> + The definition of the {@code android.content.BroadcastReceiver} classes shown in this example + is discussed in <a href="#handle_actions">Handle User Actions</a>. +</p> + + +<h2 id="support-lib">Import Support Library for Messaging</h3> + +<p> + Building notifications for use with Auto devices requires classes from the + <a href="{@docRoot}tools/support-library/features.html#v4">v4 support library</a>. Use the + <a href="{@docRoot}tools/help/sdk-manager.html">Android SDK Manager</a> to update the + <em>Extras > Android Support Repository</em> to version 9 or higher and the + <em>Extras > Android Support Library</em> to version 21.1.0 or higher. +</p> + +<p> + After you have updated the support libraries, import them into your Android Studio development + project by adding this dependency to your + <a href="{@docRoot}sdk/installing/studio-build.html#configBuild">build.gradle</a> file: +</p> + +<pre> +dependencies { + ... + compile 'com.android.support:support-v4:21.1.+' +} +</pre> + +<p> + For information about importing the support library into development projects for other + development environments, see <a href="{@docRoot}tools/support-library/setup.html">Support + Library Setup</a>. +</p> + + + +<h2 id="messaging">Notify Users of Messages</h2> + +<p> + A messaging app provides messages to a connected Auto dashboard using the <a href= + "{@docRoot}guide/topics/ui/notifiers/notifications.html">notifications</a> framework. When your + messaging app has a message for a user, you build a specially configured notification that is + received by the dashboard system and presented to the user. The Auto device manages the + presentation on the dashboard screen and may play the message via text-to-speech. The dashboard + system also handles voice interaction if the user replies to a message using verbal input. +</p> + +<p> + The messaging user interface for Auto presents users with two levels of information about + messages. The first level of notification tells users what <em>conversations</em> are + available, and who they are with, but not the content of the messages. Typically, a + conversation is one or more messages from another user to the Auto user. +</p> + +<p> + The second level of the notification is the actual content of messages in the conversation. If a + user indicates they want to hear the messages in a conversation, the Auto user interface plays + the messages using text-to-speech. +</p> + +<p> + This section describes how to notify Auto users that conversations are available and + provide the content of messages in those conversations. +</p> + + +<h3 id="build_conversation">Build message conversations</h4> + +<p> + Messaging notifications for Auto organize messages into conversations using the {@code + NotificationCompat.CarExtender.UnreadConversation} class, that represents an unread or new + portion of a conversation from a particular sender. It contains a list of messages from the + sender. +</p> + +<p> + Use the {@code UnreadConversation.Builder} class to create an unread conversation object, + as shown in the following example code: +</p> + +<pre> +// Build a RemoteInput for receiving voice input in a Car Notification +RemoteInput remoteInput = new RemoteInput.Builder(EXTRA_VOICE_REPLY) + .setLabel(getApplicationContext().getString(R.string.notification_reply)) + .build(); + +// Create an unread conversation object to organize a group of messages +// from a particular sender. +UnreadConversation.Builder unreadConvBuilder = + new UnreadConversation.Builder(participantName) + .setReadPendingIntent(msgHeardPendingIntent) + .setReplyAction(replyPendingIntent, remoteInput); +</pre> + +<p> + This conversation object includes a {@link android.app.PendingIntent}, which allows the Auto + device to signal your app that the conversation has been read by the Auto user. The construction + of this intent is discussed in the <a href="#conversation-intents">Creating conversation read and + reply intents</a> section. +</p> + +<p> + If your app supports replying to a conversation, you must call the {@code setReplyAction()} + method and provide a pending intent to pass that user action back to your app. The {@code + UnreadConversation} object you create must also include a {@link + android.support.v4.app.RemoteInput} object. This object is required because the Auto user + receiving this conversation speaks a reply, a the remote input objects lets your app get a text + version of the voice reply. +</p> + + +<h4 id="conversation-messages">Associate messages with conversations</h4> + +<p> + Messages provided for Auto must be associated with a conversation using the {@code + NotificationCompat.CarExtender.UnreadConversation} class. The following code example shows how + to associate individual messages with a conversation object. +</p> + +<pre> +// Note: Add messages from oldest to newest to the UnreadConversation.Builder +for (Iterator<String> messages = conversation.getMessages().iterator(); + messages.hasNext(); ) { + String message = messages.next(); + unreadConvBuilder.addMessage(message); +} +</pre> + +<p> + When a new message arrives in a particular conversation, your app should check if there is + already a conversation object for that particular conversation. If there is, associate the new + message with the existing conversation instead of building a new one. +</p> + + +<h4 id="conversation-intents">Create conversation read and reply intents</h4> + +<p> + Unread conversation objects contain intents for reading and replying to a conversation. You + create a {@link android.app.PendingIntent} object for each of these actions, so the Auto device + can notify your app of action taken by the Auto user on a particular conversation. +</p> + +<p> + The following example code demonstrates how to define a {@link android.app.PendingIntent} to let + your app know if a conversation was listened to by the Auto user: +</p> + +<pre> +Intent msgHeardIntent = new Intent() + .addFlags(Intent.FLAG_INCLUDE_STOPPED_PACKAGES) + .setAction(<em>com.myapp.messagingservice.ACTION_MESSAGE_HEARD</em>) + .putExtra("conversation_id", conversationId); + +PendingIntent msgHeardPendingIntent = + PendingIntent.getBroadcast(getApplicationContext(), + conversationId, + msgHeardIntent, + PendingIntent.FLAG_UPDATE_CURRENT); +</pre> + +<p> + In this example, {@code conversationId} is an integer that identifies the current conversation. + The value of {@code setAction()} is an intent filter identifier for heard messages which is + defined in your app manifest, as shown in <a href="#manifest-intent">Define read and reply intent + filters</a>. +</p> + +<p> + If your app supports replying to conversations, you also create a {@link + android.app.PendingIntent} for each conversation to notify your app that the user has replied. + The following code example shows you how to build this intent for use with a particular + conversation: +</p> + +<pre> +Intent msgReplyIntent = new Intent() + .addFlags(Intent.FLAG_INCLUDE_STOPPED_PACKAGES) + .setAction(<em>com.myapp.messagingservice.ACTION_MESSAGE_REPLY</em>) + .putExtra("conversation_id", <em>conversationId</em>); + +PendingIntent msgReplyPendingIntent = PendingIntent.getBroadcast( + getApplicationContext(), + <em>conversationId</em>, + msgReplyIntent, + PendingIntent.FLAG_UPDATE_CURRENT); +</pre> + +<p> + Once again, {@code conversationId} is an integer that uniquely identifies this conversation. The + value of {@code setAction()} is an intent filter identifier for replies which is defined in your + app manifest, as shown in <a href="#manifest-intent">Define read and reply intent filters</a>. +</p> + + +<h3 id="sending_messages">Sending Messages</h4> + +<p> + When a message arrives for a conversation, you take the following steps to dispatch it as a + notification to Auto. +</p> + +<p>First, add the message to the <code>UnreadConversation.Builder</code> for +this conversation, and update its timestamp:</p> + +<pre> +unreadConvBuilder.addMessage(<em>messageString</em>) + .setLatestTimestamp(<em>currentTimestamp</em>); +</pre> + +<p>Then create a {@link android.support.v4.app.NotificationCompat.Builder} +object that you'll use to build the actual notification. You'll need to use the +pending intents you created in the previous step.</p> + +<pre> +NotificationCompat.Builder notificationBuilder = + new NotificationCompat.Builder(getApplicationContext()) + .setSmallIcon(R.drawable.<em>notification_icon</em>) + .setLargeIcon(<em>icon_bitmap</em>) + .setContentText(<em>messageString</em>) + .setWhen(<em>currentTimestamp</em>) + .setContentTitle(<em>participant_name</em>) + .setContentIntent(msgHeardPendingIntent); + +</pre> + +<p>You'll also need to extend the {@link +android.support.v4.app.NotificationCompat.Builder} with the +<code>CarExtender</code>. This is where you actually create the +<code>UnreadConversation</code> object using the builder you just +created, and attach it to the <code>CarExtender</code>:</p> + +<pre> +notificationBuilder.extend(new CarExtender() + .setUnreadConversation(unreadConvBuilder.build()); +</pre> + +<p>Once you've done all this, you use your app's {@link +android.support.v4.app.NotificationManagerCompat} to send the notification:</p> + +<pre> +mNotificationManager = NotificationManagerCompat.from(context); +mNotificationManager.notify(<em>notificationId</em>, notificationBuilder.build()); +</pre> + +<p>In this example, <em>msgNotificationManager</em> is a +{@link android.support.v4.app.NotificationManagerCompat} you created for your app.</p> + + +<h2 id="handle_actions">Handle User Actions</h2> + +<p> + When your create and dispatch a notification for messaging, you specify intents to be triggered + when the Auto user hears the message and when the user dictates a reply. Your app indicates to + the Android framework that it handles these intends by registering them through it's manifest, as + discussed in <a href="#manifest-intent">Define read and reply intent filters</a>. +</p> + +<p> + In addition to registering these intent filters, your app must provide code to handle these + actions. Your app can do this by providing a service or {@link android.content.BroadcastReceiver} + objects that handle these intents.</p> + +<p> + For more information about intents, see <a href= + "{@docRoot}guide/components/intents-filters.html">Intents and Intent Filters</a>. +</p> + + +<h3 id="handling_msg_heard">Handling a message heard action</h3> + +<p> + When a user listens to a messaging conversation through the Auto user interface, the dashboard + device sends a read intent based on how your app defined the messaging notification. Your app + catches that intent and invokes the broadcast receiver class associated with it, or the service + method set up to handle that action. +</p> + +<p> + The following code example shows how to define a {@link android.content.BroadcastReceiver} class + to handle a received message heard intent: +</p> + +<pre> +public class MessageHeardReceiver extends BroadcastReceiver { + + @Override + public void onReceive(Context context, Intent intent) { + + // If you set up the intent as described in + // "Create conversation read and reply intents", + // you can get the conversation ID by calling: + int conversationId = intent.getIntExtra("conversation_id", -1); + + // Remove the notification to indicate it has been read + // and update the list of unread conversations in your app. + } +} +</pre> + +<p> + Once a notification is read, your app can remove it by calling + {@link android.support.v4.app.NotificationManagerCompat#cancel} with the notification ID. + Within your app, you should mark the messages provided in the notification as read. +</p> + + +<p class="note"> + <strong>Note:</strong> An alternative to this implementation is to use a service in a + {@link android.app.PendingIntent}. +</p> + + +<h3 id="handling_reply">Handling a reply action</h3> + +<p> + When a user replies to a messaging conversation through the Auto user interface, the dashboard + system sends a reply intent based on how your app defined the messaging notification. Your app + catches that intent and invokes the broadcast receiver class associated with it, or the service + method set up to handle that action. +</p> + +<p> + The following code example shows how to define a {@link android.content.BroadcastReceiver} class + to handle a received message reply intent: +</p> + +<pre> + public class MessageReplyReceiver extends BroadcastReceiver { + + + @Override + public void onReceive(Context context, Intent intent) { + // If you set up the intent as described in + // "Create conversation read and reply intents", + // you can get the conversation ID by calling: + int conversationId = intent.getIntExtra("conversation_id", -1). + + } + + /** + * Get the message text from the intent. + * Note that you should call + * RemoteInput.getResultsFromIntent() to process + * the RemoteInput. + */ + private CharSequence getMessageText(Intent intent) { + Bundle remoteInput = + RemoteInput.getResultsFromIntent(intent); + if (remoteInput != null) { + return remoteInput.getCharSequence("extra_voice_reply"); + } + return null; + } + +}</pre> diff --git a/docs/html/training/auto/start/index.jd b/docs/html/training/auto/start/index.jd new file mode 100644 index 0000000..b955cef --- /dev/null +++ b/docs/html/training/auto/start/index.jd @@ -0,0 +1,210 @@ +page.title=Getting Started with Auto +page.tags="auto", "car", "automotive" +page.article=true +page.image=auto/images/assets/icons/auto_app_in_simulator.png + +@jd:body + +<div id="tb-wrapper"> +<div id="tb"> + <h2>Dependencies and Prerequisites</h2> + <ul> + <li>Android 5.0 (API level 21) or higher</li> + </ul> + + <h2>This class teaches you how to</h2> + <ol> + <li><a href="#dev-project">Set Up an Auto Project</a></li> + <li><a href="#build-it">Build Auto Apps</a></li> + <li><a href="#test-it">Run and Test Auto Apps</a></li> + </ol> + + <h2>You should also read</h2> + <ul> + <li><a href="{@docRoot}design/auto/index.html">Designing for Auto</a></li> + <li><a href="{@docRoot}training/auto/audio/index.html">Providing Audio Playback with Auto</a></li> + <li><a href="{@docRoot}training/auto/messaging/index.html">Providing Messaging for Auto</a></li> + </ul> +</div> +</div> + +<p>Android Auto extends the Android platform into the car. When users connect +their handheld devices running Android 5.0 or higher to a compatible vehicle, +the Auto user interface 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 (like a touchscreen or dashboard +buttons).</p> + +<p>Auto currently supports two types of apps:</p> + +<ul> +<li><em>Audio apps</em> that allow users to browse and play music and spoken +audio content in the car.</li> +<li><em>Messaging apps</em> that receive incoming notifications, read messages + aloud via text-to-speech, and send replies via voice input in the car.</li> +</ul> + +<p>You can enable your existing audio and messaging apps developed for +phones and tablets to work in the car, without having to worry about +vehicle-specific hardware differences. To enable your app for Auto, your +app must target Android 5.0 (API level 21) or higher. Your app’s manifest must +also declare the car capabilities that it uses, such as audio playback or +messaging services. </p> + +<p>This lesson describes how to start building apps for Auto, including +setting up your development environment and meeting the the minimum requirements +to enable an app to communicate with Auto.</p> + +<p class="note"><strong>Important:</strong> If you are planning to develop +apps for Auto, you are encouraged to begin enabling and testing your +apps now. However, Auto-enabled apps cannot be published at this time. +Join the +<a href="http://g.co/AndroidAutoDev" class="external-link">Auto +Developers Google+ community</a> for updates on when you will be able to submit +your Auto-enabled apps.</p> + +<h2 id="dev-project">Set Up an Auto Project</h2> +<p>This section describes how to create a new app or modify an existing app to +communicate with Auto.</p> + +<h3 id="prerequisites">Prerequisites</h3> +<p>Before you begin building apps for Auto, you must:</p> + +<ul> +<li><strong><a href="{@docRoot}sdk/installing/create-project.html">Create or +update your app project</a></strong> - Android 5.0 (API level 21) provides new +APIs for implementing audio playback and messaging that is compatible with Auto. +To access the new APIs, create a project or modify an existing project to target +Android 5.0 (API level 21) or higher. This means you must set the manifest +<a href="{@docRoot}topics/manifest/uses-sdk-element.html">{@code targetSdkVersion}</a> +to 21 or higher. +</li> +<li><strong><a href="{@docRoot}tools/support-library/setup.html">Install the +support library</a></strong> - If you are building messaging apps for Auto, you +need the {@code NotificationCompat.CarExtender} class contained in the +<a href="{@docRoot}tools/support-library/features.html#v4">v4 support library</a>. +This class allows you to create notifications that are compatible with Auto +devices.</li> +</ul> + +<h3 id="auto-metadata">Declare Auto capabilities</h3> +<p>The Auto features that your app can access are controlled +by the settings in your app manifest and a separate XML configuration file. +Before adding Auto features to your app, you must first define the Auto +XML configuration file and add a manifest entry referencing your XML file.</p> + +<h4 id="auto_xml">Define the Auto XML configuration file</h4> +<p>Specify the car capabilities that your app uses in an XML file that you +place in your project’s resources directory ({@code res/xml/}). For example, to +extend an audio application for Auto, create a file called +{@code automotive_app_desc.xml} and store it under your projects’s +{@code res/xml/} folder. The {@code automotive_app_desc.xml} file contains the +following metadata:</p> +<pre> +<automotiveApp> + <uses name="media" /> +</automotiveApp> +</pre> +<p>The {@code <uses>} element declares the Auto capability your app +intends to use. Multiple {@code <uses>} tags can be added if your +application uses multiple car capabilities. The {@code name} attribute indicates +the specific capability your app uses. The values supported are:</p> +<ul> +<li>{@code media} - The app uses the Android framework APIs to play music in +a vehicle. Set this value if you are enabling an audio app for Auto.</li> +<li>{@code notification} - The app displays message notifications in the car’s +Overview screen, allows users select a message to be read aloud, and lets them +respond through voice input. Set this value if you are enabling a messaging +app for Auto. +</ul> + +<h4 id="auto_xml">Add a manifest entry</h4> +<p>In your app’s manifest ({@code AndroidManifest.xml}), provide a reference to +the Auto XML configuration file you created in the previous section. Add a +{@code "com.google.android.gms.car.application"} metadata entry under the +<a href="{@docRoot}guide/topics/manifest/application-element.html">{@code <application>}</a> +element that references your Auto XML configuration file. Omit the {@code .xml} +file extension when specifying the configuration filename.</p> +<p>The following code snippet shows how to include this reference in your +manifest.</p> +<pre> +<application> + + ... + <meta-data android:name="com.google.android.gms.car.application" + android:resource="@xml/automotive_app_desc"/> + +</application> +</pre> + +<h2 id="build-it">Add Auto Features to Your Apps</h2> +<p>After you have completed the steps described above, you're ready to add Auto +features to your apps. See these additional topics to help you build apps for +Auto:</p> + +<ul> +<li><a href="{@docRoot}training/auto/audio/index.html">Providing Audio Playback for Auto</a> +- Create apps that let users browse and play music in the car.</li> +<li><a href="{@docRoot}training/auto/messaging/index.html">Providing Messaging for Auto</a> +- Enable users to receive and reply to messages in the car.</li> +</ul> + +<p class="caution"><strong>Important:</strong> Google takes driver distraction +very seriously. There are specific design requirements your app must meet to +qualify as an Auto app on Google Play. By adhering to these +requirements, you can reduce the effort for building and testing your app. For +more information, see +<a href="{@docRoot}distribute/essentials/quality/auto.html">Auto App Quality</a>.</p> + +<h2 id="test-it">Run and Test Auto Apps</h2> + +<p>As you prepare to publish your app, make sure that your app looks correct +when projected on the Auto user interface. Use the Android Media Browser +simulator and Android Messaging simulators to view and test your audio or +messaging apps in a screen that looks similar to what is projected on Auto.</p> + +<p>To get the simulators, open the +<a href="{@docRoot}tools/help/sdk-manager.html">SDK Manager</a> and download +them from <strong>Extras > Android Auto API Simulators</strong>.</p> + +<p>Before you begin testing, compile your app in your development environment. +Install your app and the Android simulator for the features you want to test +(that is, audio or messaging) on a physical or virtual device running Android +5.0 (API level 21) or higher. To check the version of Android on the device, go +to <strong>Settings > About > Android Version</strong>.</p> + +<h3 id="testing-audio-apps">Testing audio apps</h3> +<p>To run and test audio apps:</p> + +<ol> +<li>Install the Android Media Browser simulator +({@code media-browser-simulator.apk}) on the test device. You can do this using +the <a href="{@docRoot}tools/help/adb.html#move">adb</a> command line tool.</li> +<li>Enable <a href="{@docRoot}tools/device.html#device-developer-options"> +developer options</a> on the test device.</li> +<li>Install your app on the test device.</li> +<li>Launch the Android Media Browser simulator to see how your audio app +appears in Auto. If your app does not appear, stop the simulator from +<strong>Settings > Apps</strong> then restart it.</li> +</ol> + +<h3 id="testing-messaging-apps">Testing messaging apps</h3> +<p>To run and test messaging apps:</p> + +<ol> +<li>Install the Android Messaging simulator ({@code messaging-simulator.apk}) +on the test device. You can do this using the +<a href="{@docRoot}tools/help/adb.html#move">adb</a> command line tool.</li> +<li>Enable the simulator to read notifications posted on the system: +<ol type="a"> + <li>Enable <a href="{@docRoot}tools/device.html#device-developer-options"> +developer options</a> on the test device.</li> + <li>Click <strong>Settings > Sounds & Notifications > Notification + Access</strong> and check the box labeled + <strong>Messaging Simulator</strong>.</li> +</ol> +<li>Install your app on the test device.</li> +<li>Launch the Android Messaging Simulator to see how your messaging app appears +in Auto. If your app does not appear, stop the simulator from +<strong>Settings > Apps</strong> then restart it.</li> +</ol> |