242 lines
10 KiB
Plaintext
242 lines
10 KiB
Plaintext
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">
|
|
<?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/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>
|