docs/html/wear/preview/features/bridger.jd

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>&lt;meta-data&gt;</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>
&lt;meta-data android:name=&quot;com.google.android.wearable.notificationBridgeMode&quot;
                   android:value=&quot;NO_BRIDGING&quot; /&gt;
</pre>

    <p>
      The default bridging behavior occurs if you do not
      include the <code>&lt;meta-data&gt;</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(&lt;NotificationCompat.Builder&gt;, &lt;String&gt;);
</pre>

    <p>
      For example:
    </p>

<pre>
NotificationCompat.Builder builder = new NotificationCompat.Builder(context)
&lt;set other fields&gt;;
BridgingManager.setNotificationBridgeTag(builder, &quot;foo&quot;);
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)
&lt;set other fields&gt;
.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>