| 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/preview/support/wearable/notifications/RemoteInput.html"> |
| <code>RemoteInput</code></a> using the |
| <a href="{@docRoot}reference/android/preview/support/wearable/notifications/RemoteInput.Builder.html"><code>RemoteInput.Builder</code></a> APIs. |
| The |
| <a href="{@docRoot}reference/android/preview/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/preview/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/preview/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"> |
| <?xml version="1.0" encoding="utf-8"?> |
| <resources> |
| <string-array name="reply_choices"> |
| <item>Yes</item> |
| <item>No</item> |
| <item>Maybe</item> |
| </string-array> |
| </resources> |
| </pre> |
| |
| <p>Then, inflate the string array and add it to the |
| <a href="{@docRoot}reference/android/preview/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/preview/support/wearable/notifications/RemoteInput.html"><code>RemoteInput</code></a> to the main action using |
| <a href="{@docRoot}reference/android/preview/support/wearable/notifications/WearableNotifications.Builder.html#addRemoteInputForContentIntent(android.preview.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(); |
| |
| // Create wearable notification and add remote input |
| Notification replyNotification = |
| new WearableNotifications.Builder(replyNotificationBuilder) |
| .addRemoteInputForContentIntent(replyAction) |
| .build(); |
| </pre> |
| |
| |
| <p>By using |
| <a href="{@docRoot}reference/android/preview/support/wearable/notifications/WearableNotifications.Builder.html#addRemoteInputForContentIntent(android.preview.support.wearable.notifications.RemoteInput)"> |
| <code>addRemoteInputForContentIntent()</code></a> to add the |
| <a href="{@docRoot}reference/android/preview/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/preview/support/wearable/notifications/RemoteInput.html"><code>RemoteInput</code></a> to a new action button defined by an |
| <a href="{@docRoot}reference/android/preview/support/wearable/notifications/Action.html"> |
| <code>Action</code></a> object.</p> |
| |
| <p>You should instantiate the |
| <a href="{@docRoot}reference/android/preview/support/wearable/notifications/WearableNotifications.Action.html"> |
| <code>Action</code></a> with the |
| <a href="{@docRoot}reference/android/preview/support/wearable/notifications/WearableNotifications.Action.Builder.html"><code>Action.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 |
| Action replyAction = new Action.Builder(R.drawable.ic_message, |
| "Reply", pendingIntent) |
| .addRemoteInput(remoteInput) |
| .build(); |
| </pre> |
| |
| |
| <p>After you add the |
| <a href="{@docRoot}reference/android/preview/support/wearable/notifications/RemoteInput.html"><code>RemoteInput</code></a> to the |
| <a href="{@docRoot}reference/android/preview/support/wearable/notifications/WearableNotifications.Action.html"> |
| <code>Action</code></a>, add the |
| <a href="{@docRoot}reference/android/preview/support/wearable/notifications/WearableNotifications.Action.html"> |
| <code>Action</code></a> to the |
| <a href="{@docRoot}reference/android/preview/support/wearable/notifications/WearableNotifications.Builder.html"><code>WearableNotifications.Builder</code></a> using |
| <a href="{@docRoot}reference/android/preview/support/wearable/notifications/WearableNotifications.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 |
| Action replyAction = new Action.Builder(R.drawable.ic_message, |
| "Reply", pendingIntent) |
| .addRemoteInput(remoteInput) |
| .build(); |
| |
| // Create wearable notification and add action |
| Notification replyNotification = |
| new WearableNotifications.Builder(replyNotificationBuilder) |
| .addAction(replyAction) |
| .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/preview/support/wearable/notifications/RemoteInput.Builder.html"><code>RemoteInput.Builder</code></a> constructor) |
| with the user's message as the string value.</p> |
| |
| |
| |
| |
| </body> |
| </html> |