Android/frameworks_base
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

am 66b4b317: am 0a3f9c7d: docs: Revisions to "Providing Messaging for Auto"

Browse Source 
* commit '66b4b3179b0b98e89daaacf0e4d926c72341ea6a':
  docs: Revisions to "Providing Messaging for Auto"
This commit is contained in:
Andrew Solovay
2015-03-10 15:11:01 +00:00
committed by Android Git Automerger
parent 00e3efb549 66b4b3179b
commit 5f8e08ed2c
1 changed files with 245 additions and 126 deletions
Download Patch File Download Diff File Expand all files Collapse all files

371
docs/html/training/auto/messaging/index.jd
View File

@@ -48,7 +48,7 @@ page.article=true
</a>
<p>
Staying connected through text messages is important to many drivers. Chat apps can let users
Staying connected through 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
@@ -95,6 +95,90 @@ page.article=true
has read or replied to a message.
</ul>
<h3 id="#concepts">Concepts and Objects</h3>
<p>Before you start designing your app, it's helpful to understand how Auto
handles messaging.</p>
<p>Each individual chunk of communication is a <em>message</em>. A message is a
short length of text, suitable for the Auto device to read aloud. In a chat app,
this might be a single message from one person to another: <code>"Fitzy -- Jane
can't come to the ball, her youngest has the croup. :-( --Liz"</code> In a
sports app, a message might be a single bit of news about a game: <code>"Granger
scores for Harpies at 7 minutes in."</code></p>
<p>A <em>conversation</em> is a group of messages that are all grouped together
in some way. Auto uses the conversation information to group the messages
together when presenting them to the user. In a chat app, a conversation might
be all the messages between the user and another person (for example, all
the messages back and forth between Darcy and Elizabeth). In a sports app, a
conversation might be all the messages about a particular game. Every message
belongs to a conversation, even if it's the only message in that conversation.
Each conversation has a <em>conversation name</em>.
The conversation name is used by Android Auto to
present the messages; it's up to your app to choose an appropriate conversation
name. In a chat app, the conversation name is usually the person your user is
talking to.
In a sports app, this might be the name of the teams playing in the game.</p>
<p>The v4 support library defines an {@link
android.support.v4.app.NotificationCompat.CarExtender.UnreadConversation
UnreadConversation} object. This object holds all messages in a conversation
which have not yet been heard by the user. To give those messages to the user,
you attach that {@link
android.support.v4.app.NotificationCompat.CarExtender.UnreadConversation
UnreadConversation} to a notification. However, you do not attach messages to
the {@link
android.support.v4.app.NotificationCompat.CarExtender.UnreadConversation
UnreadConversation} directly. Instead, you must first set up an {@link
android.support.v4.app.NotificationCompat.CarExtender.UnreadConversation.Builder
UnreadConversation.Builder} object for the conversation. The messages are added to the builder,
then when you are ready to send the messages, you use the builder to create the
actual {@link
android.support.v4.app.NotificationCompat.CarExtender.UnreadConversation
UnreadConversation} and attach the {@link
android.support.v4.app.NotificationCompat.CarExtender.UnreadConversation
UnreadConversation} to the notification.</p>
<p class="note"><strong>Note:</strong> When Auto presents messages to the
user, it uses the notification <em>tag</em> and <em>ID</em> to determine which conversation the
messages belong to. It is important to use the same tag and ID for all messages in
a conversation, and to not use that tag for other conversations.</p>
<h3 id="#workflow">Workflow</h3>
<p>This section describes how the mobile device interacts with Auto to present
messages to the user.</p>
<ol>
<li>The app receives a message that it wants to pass on to the user. It attaches
the message to an {@link
android.support.v4.app.NotificationCompat.CarExtender.UnreadConversation
UnreadConversation} object and attaches it to a notification. That notification
is associated with a {@link
android.support.v4.app.NotificationCompat.CarExtender CarExtender} object, which
indicates that the notification can be handled by Android Auto.</li>
<li>The app posts the notification. The Android notification framework passes the
message to Auto. Auto uses the notification tag and ID to determine which conversation
the message belongs to, and presents the message to the user in an appropriate
way.</li>
<li>When the user listens to the message, Auto triggers the app's message heard
pending intent. The app should discard the {@link
android.support.v4.app.NotificationCompat.CarExtender.UnreadConversation
UnreadConversation} object and its builder at this time, since the messages
contained in those objects have been heard by the user.</li>
<li>If the user sends a reply, Auto triggers the app's "message reply" intent and
attaches a transcript of the user's response. The app can take appropriate
action, based on the app's logic. For example, a chat app might interpret the
reply as a message to go to the other conversation participants, while a sports
app might try to interpret the "reply" as a request for other information
("What's the score in the Sharks game?").</li>
</ol>
<h2 id="#manifest">Configure Your Manifest</h2>
@@ -104,7 +188,6 @@ page.article=true
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>
@@ -159,26 +242,28 @@ page.article=true
<pre>
&lt;application&gt;
...
&lt;receiver android:name="<em>.MyMessageReadReceiver</em>"&gt;
&lt;receiver android:name=".MyMessageHeardReceiver"&gt;
&lt;intent-filter&gt;
&lt;action android:name="<em>com.myapp.messagingservice.ACTION_MESSAGE_HEARD</em>"/&gt;
&lt;action android:name="com.myapp.messagingservice.MY_ACTION_MESSAGE_HEARD"/&gt;
&lt;/intent-filter&gt;
&lt;/receiver&gt;
&lt;receiver android:name="<em>.MyMessageReplyReceiver</em>"&gt;
&lt;receiver android:name=".MyMessageReplyReceiver"&gt;
&lt;intent-filter&gt;
&lt;action android:name="<em>com.myapp.messagingservice.ACTION_MESSAGE_REPLY</em>"/&gt;
&lt;action android:name="com.myapp.messagingservice.MY_ACTION_MESSAGE_REPLY"/&gt;
&lt;/intent-filter&gt;
&lt;/receiver&gt;
...
&lt;/application&gt;
</pre>
<p>
The definition of the {@link android.content.BroadcastReceiver} classes shown in this example
is discussed in <a href="#handle_actions">Handle User Actions</a>.
</p>
<p> In this example, <code>"MyMessageReadReceiver"</code> and
<code>"MyMessageReplyReceiver"</code> are the names of the {@link
android.content.BroadcastReceiver} subclasses you define to handle the
intents. You can choose whatever you like as the action names, but it's best
to prepend your package name to ensure that the action names are unique. For
more information about handling actions, see <a href="#handle_actions">Handle
User Actions</a>. </p>
<h2 id="support-lib">Import Support Library for Messaging</h3>
@@ -199,7 +284,7 @@ page.article=true
<pre>
dependencies {
...
compile 'com.android.support:support-v4:21.0.+'
compile 'com.android.support:support-v4:21.0.2'
}
</pre>
@@ -240,79 +325,6 @@ dependencies {
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 {@link
android.support.v4.app.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 {@link android.support.v4.app.NotificationCompat.CarExtender.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 {@link android.support.v4.app.NotificationCompat.CarExtender.UnreadConversation.Builder#setReplyAction setReplyAction()}
method and provide a pending intent to pass that user action back to your app. The
{@link android.support.v4.app.NotificationCompat.CarExtender.UnreadConversation}
object you create must also include a {@link
android.support.v4.app.RemoteInput} object. When the Auto user
receiving this conversation speaks a reply, 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
{@link android.support.v4.app.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&lt;String&gt; 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>
@@ -323,28 +335,27 @@ for (Iterator&lt;String&gt; messages = conversation.getMessages().iterator();
<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:
your app know if a conversation was read to 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", <em>conversationId</em>);
.setAction("com.myapp.messagingservice.MY_ACTION_MESSAGE_HEARD")
.putExtra("conversation_id", thisConversationId);
PendingIntent msgHeardPendingIntent =
PendingIntent.getBroadcast(getApplicationContext(),
<em>conversationId</em>,
thisConversationId,
msgHeardIntent,
PendingIntent.FLAG_UPDATE_CURRENT);
</pre>
<p>
In this example, {@code conversationId} is an integer that identifies the current conversation.
The value of {@link android.content.Intent#setAction 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>In this example, {@code thisConversationId} is an integer that identifies the
current conversation. The value of {@link android.content.Intent#setAction
Intent.setAction()} is the intent filter identifier for heard messages which you
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
@@ -356,22 +367,79 @@ PendingIntent msgHeardPendingIntent =
<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>);
.setAction("com.myapp.messagingservice.MY_ACTION_MESSAGE_REPLY")
.putExtra("conversation_id", thisConversationId);
PendingIntent msgReplyPendingIntent = PendingIntent.getBroadcast(
getApplicationContext(),
<em>conversationId</em>,
thisConversationId,
msgReplyIntent,
PendingIntent.FLAG_UPDATE_CURRENT);
</pre>
<p> Once again, {@code thisConversationId} is an integer that uniquely identifies
this conversation, and the value you pass to {@link
android.content.Intent#setAction Intent.setAction()} is the intent filter
identifier you defined for replies in your app manifest. </p>
<h3 id="build_conversation">Set up the conversation builder</h4>
<p>
Once again, {@code conversationId} is an integer that uniquely identifies this conversation. The
value of {@link android.content.Intent#setAction 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>.
Messaging notifications for Auto organize messages into conversations using the {@link
android.support.v4.app.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>
You generally do not configure the {@link
android.support.v4.app.NotificationCompat.CarExtender.UnreadConversation UnreadConversation}
directly. Instead, you configure an
{@link android.support.v4.app.NotificationCompat.CarExtender.UnreadConversation.Builder
UnreadConversation.Builder} with the information about the conversation,
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(MY_VOICE_REPLY_KEY)
.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(conversationName)
.setReadPendingIntent(msgHeardPendingIntent)
.setReplyAction(msgReplyPendingIntent, remoteInput);
</pre>
<p class="note">
<strong>Note:</strong> You won't actually create the {@link
android.support.v4.app.NotificationCompat.CarExtender.UnreadConversation
UnreadConversation} until you are almost ready to send the message.
</p>
<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
{@link android.support.v4.app.NotificationCompat.CarExtender.UnreadConversation.Builder#setReplyAction
UnreadConversation.Builder.setReplyAction()}
method and provide a pending intent to pass that user action back to your app. The
{@link android.support.v4.app.NotificationCompat.CarExtender.UnreadConversation
UnreadConversation}
object you create must also include a {@link
android.support.v4.app.RemoteInput} object. When the Auto user
receiving this conversation speaks a reply, the remote input objects lets your app get a text
version of the voice reply.
</p>
<h3 id="sending_messages">Sending Messages</h4>
@@ -381,49 +449,99 @@ PendingIntent msgReplyPendingIntent = PendingIntent.getBroadcast(
</p>
<p>First, add the message to the {@link
android.support.v4.app.NotificationCompat.CarExtender.UnreadConversation.Builder}
for this conversation, and update its timestamp:</p>
android.support.v4.app.NotificationCompat.CarExtender.UnreadConversation.Builder
UnreadConversation.Builder} for this conversation, and update its timestamp:</p>
<pre>
unreadConvBuilder.addMessage(<em>messageString</em>)
.setLatestTimestamp(<em>currentTimestamp</em>);
unreadConvBuilder.addMessage(messageString)
.setLatestTimestamp(currentTimestamp);
</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
<p class="note"><strong>Note:</strong> If you are sending several messages at
once, add them to the {@link
android.support.v4.app.NotificationCompat.CarExtender.UnreadConversation.Builder
UnreadConversation.Builder} in order, from oldest to newest.</p>
<p>Then create the {@link android.support.v4.app.NotificationCompat.Builder
NotificationCompat.Builder}
object that builds the actual notification. You 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);
.setSmallIcon(smallIconResourceID)
.setLargeIcon(largeIconBitmap);
</pre>
<dl>
<dt><code>smallIconResourceID</code></dt>
<dd>The resource ID of a small icon to use for the conversation. This is
typically a generic icon for the messaging app.</dd>
<dt><code>largeIconBitmap</code></dt>
<dd>A {@link android.graphics.Bitmap} of a large version of the icon. This
is typically a conversation-specific graphic. For example, if this is a
chat app, the large icon would be a picture of the person the user is
chatting with.</dd>
<dt><code>messageString</code></dt>
<dd>The text of the message you want to send. (If you are sending several
messages at once, concatenate them into a single string, with the oldest
message first.)</dd>
<dt><code>currentTimestamp</code></dt>
<dd>The message timestamp. (If you are sending several messages at once,
use the timestamp of the most recent message.)</dd>
<dt><code>conversationName</code></dt>
<dd>The name you chose for this conversation (for example, the name of the
person the user is chatting with). This should be the same conversation
name you used when you created the {@link
android.support.v4.app.NotificationCompat.CarExtender.UnreadConversation.Builder
UnreadConversation.Builder}.</dd>
<dt><code>msgHeardPendingIntent</code></dt>
<dd>The pending intent object you created in
<a href="#conversation-intents">Create conversation read and reply
intents</a>.</dd>
</dl>
<p>You'll also need to extend the {@link
android.support.v4.app.NotificationCompat.Builder} with the {@link
android.support.v4.app.NotificationCompat.CarExtender}. This is where you
actually create the {@link android.support.v4.app.NotificationCompat.CarExtender.UnreadConversation} object using the builder you
android.support.v4.app.NotificationCompat.Builder NotificationCompat.Builder} with the {@link
android.support.v4.app.NotificationCompat.CarExtender CarExtender}. This is where you
actually create the
{@link android.support.v4.app.NotificationCompat.CarExtender.UnreadConversation
UnreadConversation} object using the builder you
just created, and attach it to the {@link
android.support.v4.app.NotificationCompat.CarExtender}:</p>
android.support.v4.app.NotificationCompat.CarExtender CarExtender}:</p>
<pre>
notificationBuilder.extend(new CarExtender()
.setUnreadConversation(unreadConvBuilder.build());
</pre>
<p class="note"><strong>Note:</strong> If you wish, you can set an override icon
or color for the {@link android.support.v4.app.NotificationCompat.CarExtender
CarExtender} by calling {@link
android.support.v4.app.NotificationCompat.CarExtender#setLargeIcon
setLargeIcon()} or {@link
android.support.v4.app.NotificationCompat.CarExtender#setColor setColor()}. The
override icon or color is used when the notification is handled by a car, and
has no effect if the notification is handled on the Android device. This is
useful if the notification's default icon or color are not suitable for the
car's display.</p>
<p>Once you've done all this, you use your app's {@link
android.support.v4.app.NotificationManagerCompat} to send the notification:</p>
<pre>
NotificationManagerCompat msgNotificationManager =
NotificationManagerCompat.from(context);
msgNotificationManager.notify(<em>notificationId</em>, notificationBuilder.build());
msgNotificationManager.notify(notificationTag,
notificationId, notificationBuilder.build());
</pre>
<h2 id="handle_actions">Handle User Actions</h2>
@@ -431,7 +549,7 @@ msgNotificationManager.notify(<em>notificationId</em>, notificationBuilder.build
<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
the Android framework that it handles these intends by registering them through its manifest, as
discussed in <a href="#manifest-intent">Define read and reply intent filters</a>.
</p>
@@ -461,7 +579,7 @@ msgNotificationManager.notify(<em>notificationId</em>, notificationBuilder.build
</p>
<pre>
public class MessageHeardReceiver extends BroadcastReceiver {
public class MyMessageHeardReceiver extends BroadcastReceiver {
&#64;Override
public void onReceive(Context context, Intent intent) {
@@ -469,7 +587,7 @@ public class MessageHeardReceiver extends BroadcastReceiver {
// 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);
int thisConversationId = intent.getIntExtra("conversation_id", -1);
// Remove the notification to indicate it has been read
// and update the list of unread conversations in your app.
@@ -479,7 +597,8 @@ public class MessageHeardReceiver extends BroadcastReceiver {
<p>
Once a notification is read, your app can remove it by calling
{@link android.support.v4.app.NotificationManagerCompat#cancel} with the notification ID.
{@link android.support.v4.app.NotificationManagerCompat#cancel
NotificationManagerCompat.cancel()} with the notification ID.
Within your app, you should mark the messages provided in the notification as read.
</p>
@@ -505,7 +624,7 @@ public class MessageHeardReceiver extends BroadcastReceiver {
</p>
<pre>
public class MessageReplyReceiver extends BroadcastReceiver {
public class MyMessageReplyReceiver extends BroadcastReceiver {
&#64;Override
@@ -513,7 +632,7 @@ public class MessageHeardReceiver extends BroadcastReceiver {
// 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).
int thisConversationId = intent.getIntExtra("conversation_id", -1).
}
@@ -527,7 +646,7 @@ public class MessageHeardReceiver extends BroadcastReceiver {
Bundle remoteInput =
RemoteInput.getResultsFromIntent(intent);
if (remoteInput != null) {
return remoteInput.getCharSequence("extra_voice_reply");
return remoteInput.getCharSequence(MY_VOICE_REPLY_KEY);
}
return null;
}