path: root/docs/html/wear/notifications/remote-input.jd

page.title=Receiving Voice Input from a Notification

@jd:body

<img src="{@docRoot}wear/images/13_voicereply.png" height="200" width="169" style="float:right;margin:0 0 20px 40px" />

<img src="{@docRoot}wear/images/03_actions.png" height="200" width="169" style="float:right;margin:0 0 20px 40px" />

<p>If your notification includes an action to respond with text,
    such as to reply to an email, it should normally launch an activity
    on the handheld device. However, when your notification appears on an Android wearable, you can
    allow users to dictate a reply with voice input. You can also provide pre-defined text
    messages for the user to select.</p>

<p>When the user replies with voice or selects one of the available
messages, the system sends the message to your app on the connected handheld device.
The message is attached as an extra in the {@link android.content.Intent} you specified
to be used for the notification action.</p>

<p class="note"><strong>Note:</strong> When developing with the Android emulator,
you must type text replies into the voice input field, so be sure you have enabled
<strong>Hardware keyboard present</strong> in the AVD settings.</p>


<h2 id="RemoteInput">Define the Remote Input</h2>

<p>To create an action that supports voice input, first create an instance of
  <a href="{@docRoot}reference/android/support/wearable/notifications/RemoteInput.html">
<code>RemoteInput</code></a> using the
  <a href="{@docRoot}reference/android/support/wearable/notifications/RemoteInput.Builder.html"><code>RemoteInput.Builder</code></a> APIs.
    The
  <a href="{@docRoot}reference/android/support/wearable/notifications/RemoteInput.Builder.html"><code>RemoteInput.Builder</code></a> constructor takes a string that the system
    will use as a key for the {@link android.content.Intent} extra that carries the reply message
    to your app on the handheld.</p>

<p>For example, here's how to create a new
  <a href="{@docRoot}reference/android/support/wearable/notifications/RemoteInput.html">
<code>RemoteInput</code></a> object that provides a custom
    label for the voice input prompt:</p>

<pre class="prettyprint">
// Key for the string that's delivered in the action's intent
private static final String EXTRA_VOICE_REPLY = "extra_voice_reply";

String replyLabel = getResources().getString(R.string.reply_label);

RemoteInput remoteInput = new RemoteInput.Builder(EXTRA_VOICE_REPLY)
        .setLabel(replyLabel)
        .build();
</pre>


<h3>Add Pre-defined Text Responses</h3>

<img src="{@docRoot}wear/images/12_voicereply.png" height="200" style="float:right;margin:0 0 20px 40px" />

<p>In addition to allowing voice input, you can
    provide up to five text responses that the user can select for quick replies. Call
  <a href="{@docRoot}reference/android/support/wearable/notifications/RemoteInput.Builder.html#setChoices(java.lang.String[])"><code>setChoices()</code></a> and pass it a string array.</p>

<p>For example, you may define some responses in a resource array:</p>

<p class="code-caption">res/values/strings.xml</code>
<pre class="prettyprint">
&lt;?xml version="1.0" encoding="utf-8"?>
&lt;resources>
    &lt;string-array name="reply_choices">
        &lt;item>Yes&lt;/item>
        &lt;item>No&lt;/item>
        &lt;item>Maybe&lt;/item>
    &lt;/string-array>
&lt;/resources>
</pre>

<p>Then, inflate the string array and add it to the
  <a href="{@docRoot}reference/android/support/wearable/notifications/RemoteInput.html"><code>RemoteInput</code></a>:</p>

<pre>
String replyLabel = getResources().getString(R.string.reply_label);
String[] replyChoices = getResources().getStringArray(R.array.reply_choices);

RemoteInput remoteInput = new RemoteInput.Builder(EXTRA_VOICE_REPLY)
        .setLabel(replyLabel)
        .setChoices(replyChoices)
        .build();
</pre>




<h2 id="PrimaryAction">Receive Voice Input for the Primary Action</h2>

<p>If "Reply" is your notification's primary action (defined by the {@link
android.support.v4.app.NotificationCompat.Builder#setContentIntent setContentIntent()}
method), then you should attach the
  <a href="{@docRoot}reference/android/support/wearable/notifications/RemoteInput.html"><code>RemoteInput</code></a> to the main action using
  <a href="{@docRoot}reference/android/support/wearable/notifications/WearableNotificationOptions.Builder.html#addRemoteInputForContentIntent(android.support.wearable.notifications.RemoteInput)">
<code>addRemoteInputForContentIntent()</code></a>. For example:</p>

<pre>
// Create intent for reply action
Intent replyIntent = new Intent(this, ReplyActivity.class);
PendingIntent replyPendingIntent =
        PendingIntent.getActivity(this, 0, replyIntent, 0);

// Build the notification
NotificationCompat.Builder replyNotificationBuilder =
        new NotificationCompat.Builder(this)
        .setSmallIcon(R.drawable.ic_new_message)
        .setContentTitle("Message from Travis")
        .setContentText("I love key lime pie!")
        .setContentIntent(replyPendingIntent);

// Create the remote input
RemoteInput remoteInput = new RemoteInput.Builder(EXTRA_VOICE_REPLY)
        .setLabel(replyLabel)
        .build();

// Add remote input to wearable options and apply to notification
Notification replyNotification =
        new WearableNotificationOptions.Builder()
        .addRemoteInputForContentIntent(remoteInput)
        .build()
        .applyTo(replyNotificationBuilder)
        .build();
</pre>

<p>By using
  <a href="{@docRoot}reference/android/support/wearable/notifications/WearableNotificationOptions.Builder.html#addRemoteInputForContentIntent(android.support.wearable.notifications.RemoteInput)">
<code>addRemoteInputForContentIntent()</code></a> to add the
  <a href="{@docRoot}reference/android/support/wearable/notifications/RemoteInput.html"><code>RemoteInput</code></a> object to the notification's primary action,
the button that normally appears as an "Open" action becomes the "Reply" action
and starts the voice input UI when users select it on Android Wear.</p>



<h2 id="NewAction">Receive Voice Input for a Secondary Action</h2>

<p>If the "Reply" action is not your notification's primary action and you want to enable
voice input for a secondary action, add the
  <a href="{@docRoot}reference/android/support/wearable/notifications/RemoteInput.html"><code>RemoteInput</code></a> to a new action button defined by an
  <a href="{@docRoot}reference/android/support/wearable/notifications/WearableAction.html">
<code>Action</code></a> object.</p>

<p>You should instantiate the
  <a href="{@docRoot}reference/android/support/wearable/notifications/WearableAction.html">
<code>WearableAction</code></a> with the
  <a href="{@docRoot}reference/android/support/wearable/notifications/WearableAction.Builder.html"><code>WearableAction.Builder()</code></a>
constructor, which takes an icon and text label for the action button, plus the
{@link android.app.PendingIntent}
the system should use to invoke your app when the user selects the action. For example:</p>

<pre>
// Create the pending intent to fire when the user selects the action
Intent replyIntent = new Intent(this, ReplyActivity.class);
PendingIntent pendingReplyIntent =
        PendingIntent.getActivity(this, 0, replyIntent, 0);

// Create the remote input
RemoteInput remoteInput = new RemoteInput.Builder(EXTRA_VOICE_REPLY)
        .setLabel(replyLabel)
        .build();

// Create the notification action
WearableAction replyAction = new WearableAction.Builder(R.drawable.ic_message,
        "Reply", pendingIntent)
        .addRemoteInput(remoteInput)
        .build();
</pre>


<p>After you add the
  <a href="{@docRoot}reference/android/support/wearable/notifications/RemoteInput.html"><code>RemoteInput</code></a> to the
  <a href="{@docRoot}reference/android/support/wearable/notifications/WearableAction.html">
<code>Wearablection</code></a>, set the
  <a href="{@docRoot}reference/android/support/wearable/notifications/WearableAction.html">
<code>WearableAction</code></a> on the
  <a href="{@docRoot}reference/android/support/wearable/notifications/WearableNotificationOptions.Builder.html"><code>WearableNotifications.Builder</code></a> using
  <a href="{@docRoot}reference/android/support/wearable/notifications/WearableNotificationsOptions.Builder.html#addAction(Action)"><code>addAction()</code></a>.
For example:</p>

<pre>
// Create basic notification builder
NotificationCompat.Builder replyNotificationBuilder =
        new NotificationCompat.Builder(this)
                .setContentTitle("New message");

// Create the notification action and add remote input
WearableAction replyAction = new WearableAction.Builder(R.drawable.ic_message,
        "Reply", pendingIntent)
        .addRemoteInput(remoteInput)
        .build();

// Create wearable notification and add action
Notification replyNotification =
        new WearableNotificationOptions.Builder()
                .addAction(replyAction)
                .build()
                .applyTo(replyNotificationBuilder)
                .build();
</pre>


<p>Now, when the user selects "Reply" from an Android wearable, the system prompts the user
    for voice input (and shows the list of pre-defined replies, if provided).
    Once the user completes a response, the system invokes
    the {@link android.content.Intent} attached to the action and adds the
<code>EXTRA_VOICE_REPLY</code> extra (the string
    you passed to the
  <a href="{@docRoot}reference/android/support/wearable/notifications/RemoteInput.Builder.html"><code>RemoteInput.Builder</code></a> constructor)
  with the user's message as the string value.</p>

<h2 id="ObtainInput">Obtaining the Voice Input as a String</h2>
<p>To obtain the user's voice input, call
<a href="{@docRoot}reference/android/support/wearable/notifications/RemoteInput.html#getResultsFromIntent(Intent)"><code>getResultsFromIntent()</code></a>,
passing in the "Reply" action's intent. This method returns
a {@link android.os.Bundle} that represents the intent's extras. You can then query the
{@link android.os.Bundle} to obtain the user's voice input string.
</p>
<p>
The following code shows a method that accepts an intent and returns the voice input string,
which is referenced by the <code>EXTRA_VOICE_REPLY</code> key that is used in the previous examples:
</p>
<pre>
/**
 * Obtain the intent that started this activity by calling
 * Activity.getIntent() and pass it into this method to
 * get the associated voice input string.
 */
private String getMessageText(Intent intent) {
    Bundle remoteInput = RemoteInput.getResultsFromIntent(intent);
        if (remoteInput != null) {
            return remoteInput.getString(Intent.EXTRA_VOICE_REPLY);
        }
    }
    return null;
}
</pre>

</body>
</html>