docs: Revisions to "Providing Messaging for Auto"

</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

    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>

  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>

<pre>

<application>

    ...

    &lt;receiver android:name="<em>.MyMessageReadReceiver</em>"&gt;

    <receiver android:name=".MyMessageHeardReceiver">

        <intent-filter>

          &lt;action android:name="<em>com.myapp.messagingservice.ACTION_MESSAGE_HEARD</em>"/&gt;

          <action android:name="com.myapp.messagingservice.MY_ACTION_MESSAGE_HEARD"/>

        </intent-filter>

    </receiver>

    &lt;receiver android:name="<em>.MyMessageReplyReceiver</em>"&gt;

    <receiver android:name=".MyMessageReplyReceiver">

        <intent-filter>

          &lt;action android:name="<em>com.myapp.messagingservice.ACTION_MESSAGE_REPLY</em>"/&gt;

          <action android:name="com.myapp.messagingservice.MY_ACTION_MESSAGE_REPLY"/>

        </intent-filter>

    </receiver>

    ...

</application>

</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>

<pre>

dependencies {

    ...

    compile 'com.android.support:support-v4:21.0.+'

    compile 'com.android.support:support-v4:21.0.2'

}

</pre>

  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<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>

<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

<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>

  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>

  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>.

  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>

</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>

<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>

</p>

<pre>

public class MessageHeardReceiver extends BroadcastReceiver {

public class MyMessageHeardReceiver 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);

        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.

<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>

</p>

<pre>

  public class MessageReplyReceiver extends BroadcastReceiver {

  public class MyMessageReplyReceiver extends BroadcastReceiver {

    @Override

        // 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).

    }

        Bundle remoteInput =

            RemoteInput.getResultsFromIntent(intent);

        if (remoteInput != null) {

            return remoteInput.getCharSequence("extra_voice_reply");

            return remoteInput.getCharSequence(MY_VOICE_REPLY_KEY);

        }

        return null;

    }