page.title=Bridging Mode for Notifications
meta.keywords="wear-preview"
page.tags="wear-preview"
@jd:body
<div id="qv-wrapper">
<div id="qv">
<ul>
<li>
<a href=
"#using-an-entry-in-the-manifest-file">Specifying a Bridging Configuration in the Manifest File</a>
</li>
<li>
<a href=
"#specifying-a-bridging-configuration-at-runtime">Specifying a Bridging Configuration at Runtime</a>
</li>
<li>
<a href=
"#existing-method-of-preventing-bridging">Existing Method of Preventing Bridging</a>
</li>
<li>
<a href=
"#using_a_dismissal_id_to_sync_notification_dismissals">Using a Dismissal ID to Sync Notification Dismissals</a>
</li>
</ul>
</div>
</div>
<p>
By default, notifications <a href=
"{@docRoot}training/wearables/notifications/index.html">are bridged
(shared)</a> from an app on a companion phone to the watch. If you build
a standalone watch app and have a companion phone app, they may duplicate
notifications. The Android Wear 2.0 Preview includes
features to handle this problem of repeated notifications.
</p>
<p>
With the Android Wear 2.0 Preview, developers can change the behavior of
notifications with one or more of the following:
</p>
<ul>
<li>Specifying a bridging configuration in the manifest file
</li>
<li>Specifying a bridging configuration at runtime
</li>
<li>Setting a dismissal ID so notification dismissals are synced across
devices
</li>
</ul>
<h2 id="using-an-entry-in-the-manifest-file">
Specifying a Bridging Configuration in the Manifest File
</h2>
<p>
An app's Android manifest file can indicate that notifications from the
corresponding phone app should not be bridged to the watch. Specifically,
to prevent bridging of notifications from a phone app, you can use a
<code><meta-data></code>
entry in the manifest file of the watch app (e.g. the standalone watch
app), as follows:
</p>
<pre>
com.google.android.wearable.notificationBridgeMode
</pre>
<p>
Setting that entry to <code>NO_BRIDGING</code> will prevent bridging:
</p>
<pre>
<meta-data android:name="com.google.android.wearable.notificationBridgeMode"
android:value="NO_BRIDGING" />
</pre>
<p>
The default bridging behavior occurs if you do not
include the <code><meta-data></code> entry or
if you specify a value of <code>BRIDGING</code> instead of
<code>NO_BRIDGING</code>.
</p>
<p>
For an existing app, if you are using
Google Cloud Messaging (GCM) or Firebase Cloud
Messaging (FCM) to send notification alerts to devices,
you may already have disabled bridging in case a phone is not
connected at the time of receiving an alert.
In this case, you may still want to dismiss the notification
across other devices when it is dismissed in a watch app.
</p>
<p>
The bridging configuration that is set in the manifest takes effect as
soon as a watch app is installed.
</p>
<h2 id="specifying-a-bridging-configuration-at-runtime">
Specifying a Bridging Configuration at Runtime
</h2>
<p>
This section describes how to specify a bridging configuration at runtime
using the <code>BridgingManager</code> class
<code>(android.support.wearable.notifications.BridgingManager)</code>.
</p>
<p>
You can set a bridging mode, and optionally set tags for notifications
that are exempt from the bridging mode, using a
<code>BridgingManager</code> object. Specifically, create a
<code>BridgingConfig</code> object and set it as shown in this section,
optionally using the <code>setBridgingEnabled</code> method. If you
specify a bridging configuration at runtime, then if the
<code>setBridgingEnabled</code> method is not set, bridging is enabled by
default.
</p>
<p>
Specifying a bridging configuration at runtime overrides a
bridging-related setting in the Android manifest file.
</p>
<h3 id="disable-bridging-for-all-notifications">
Disable bridging for all notifications
</h3>
<p>
You can use the <code>setBridgingEnabled</code> method, as follows:
</p>
<pre>
BridgingManager.setConfig(context,
new BridgingConfig.Builder(context)
.setBridgingEnabled(false)
.build());
</pre>
<p>
If the above setter is not called, the bridging mode defaults to true.
Here is an example of setting tags without using the
<code>setBridgingEnabled</code> method, excluding notifications with a
tag of <code>foo</code> or <code>bar</code>:
</p>
<pre>
BridgingManager.setConfig(context,
new BridgingConfig.Builder(context)
.addExcludedTag("foo")
.addExcludedTag("bar")
.build());
</pre>
<h3 id="exempt-notifications-that-are-tagged">
Exempt notifications that are tagged
</h3>
<p>
You can disable bridging for all notifications except those with certain
tags.
</p>
<p>
For example, you can disable bridging, except for notifications tagged as
<code>foo</code> or <code>bar,</code> with the following:
</p>
<pre>
BridgingManager.setConfig(context,
new BridgingConfig.Builder(context)
.setBridgingEnabled(false)
.addExcludedTag("foo")
.addExcludedTag("bar")
.build());
</pre>
<p>
As another example, you can disable bridging for all notifications except
for notifications tagged as <code>foo</code>, <code>bar</code> or
<code>baz</code>.
</p>
<pre>
BridgingManager.setConfig(context,
new BridgingConfig.Builder(context)
.setBridgingEnabled(false)
.addExcludedTags(Arrays.asList("foo", "bar", "baz"))
.build());
</pre>
<h3 id="enable-bridging-except-for-notifications-with-certain-tags">
Enable bridging except for notifications with certain tags
</h3>
<p>
You can enable bridging for all notifications except those with certain
tags.
</p>
<p>
For example, you can enable bridging for all notifications, except for
notifications tagged as <code>foo</code> or <code>bar</code>, with the
following:
</p>
<pre>
BridgingManager.setConfig(context,
new BridgingConfig.Builder(context)
.setBridgingEnabled(true)
.addExcludedTag("foo")
.addExcludedTag("bar")
.build());
</pre>
<h3 id="setting-a-bridge-tag">
Setting a bridge tag
</h3>
<p>
A bridge tag can be set on a notification by calling the
<code>setNotificationBridgeTag</code> method as follows:
</p>
<pre>
BridgingManager.setNotificationBridgeTag(<NotificationCompat.Builder>, <String>);
</pre>
<p>
For example:
</p>
<pre>
NotificationCompat.Builder builder = new NotificationCompat.Builder(context)
<set other fields>;
BridgingManager.setNotificationBridgeTag(builder, "foo");
Notification notification = builder.build();
</pre>
<h2 id="existing-method-of-preventing-bridging">
Existing Method of Preventing Bridging
</h2>
<p>
An existing way to prevent bridging is with the
<code>Notification.Builder</code> class; specify <code>true</code> in the
<a href=
"http://developer.android.com/reference/android/app/Notification.Builder.html#setLocalOnly(boolean)">
setLocalOnly</a> method.
</p>
<p>
However, this way to prevent bridging may not be preferable. For example,
if a user installs a phone app but not the corresponding watch app, the
<code>setLocalOnly</code> method could prevent the bridging of helpful
notifications. Additionally, users may have multiple paired watches and
the watch app may not be installed on all of them.
</p>
<h2 id="using_a_dismissal_id_to_sync_notification_dismissals">
Using a Dismissal ID to Sync Notification Dismissals
</h2>
<p>
If you prevent bridging with the Bridging mode feature, dismissals
(cancellations) of notifications are not synced across a user's devices.
However, the following methods of the <a href=
"http://developer.android.com/reference/android/support/v4/app/NotificationCompat.WearableExtender.html">
NotificationCompat.WearableExtender</a> class enable you to use dismissal
IDs:
</p>
<pre>
public WearableExtender setDismissalId(String dismissalId)
public String getDismissalId()
</pre>
<p>
To enable a dismissal to be synced, use the <code>setDismissalId()</code>
method. For each notification, pass a globally unique ID, as a string,
when you call the <code>setDismissalId()</code> method. When the
notification is dismissed, all other notifications with the same
dismissal ID are dismissed on the watch(es) and on the companion phone.
To retrieve a dismissal ID, use <code>getDismissalId()</code>.
</p>
<p>
In the following example, syncing of dismissals is enabled because a
globally unique ID is specified for a new notification:
</p>
<pre>
NotificationCompat.WearableExtender wearableExtender =
new NotificationCompat.WearableExtender().setDismissalId("abc123");
Notification notification = new NotificationCompat.Builder(context)
<set other fields>
.extend(wearableExtender)
.build();
</pre>
<p>
Dismissal IDs work if a watch is paired to an Android phone, but not if a
watch is paired to an iPhone.
</p>