Merge "Docs: Preview 3 - Update to bridging of notifications" into nyc-dev

    <div id="qv-wrapper">

      <div id="qv">

        <ol>

        <ul>

          <li>

            <a href=

            "#preventing_bridging_with_the_bridging_mode_feature">Preventing

            Bridging with the Bridging Mode Feature</a>

            "#using-an-entry-in-the-manifest-file">Specifying a Bridging Configuration in the Manifest File</a>

          </li>

          <li>

            <a href=

            "#using_a_dismissal_id_to_sync_notification_dismissals">Using a

            Dismissal ID to Sync Notification Dismissals</a>

            "#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>

        </ol>

          <li>

            <a href=

            "#using_a_dismissal_id_to_sync_notification_dismissals">Using a Dismissal ID to Sync Notification Dismissals</a>

          </li>

        </ul>

      </div>

    </div>

      "{@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 a Bridging mode

      feature to handle this problem of repeated notifications.

      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 the following:

      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 in the standalone app's Android manifest file that

      notifications from the corresponding phone app should not be

      bridged to the watch

      <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

      </li>

    </ul>

    <h2 id="preventing_bridging_with_the_bridging_mode_feature">

      Preventing Bridging with the Bridging Mode Feature

    <h2 id="using-an-entry-in-the-manifest-file">

      Specifying a Bridging Configuration in the Manifest File

    </h2>

    <p>

      To prevent bridging of notifications from a phone app, you can use an

      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>

    </p>

<pre>

<meta-data android:name="com.google.android.wearable.notificationBridgeMode"

                   android:value="NO_BRIDGING" />

<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 entry or

      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>

    <h3 id="existing_method_of_preventing_bridging">

      Existing method of preventing bridging

    <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=

      "{@docRoot}reference/android/app/Notification.Builder.html#setLocalOnly(boolean)">

      "http://developer.android.com/reference/android/app/Notification.Builder.html#setLocalOnly(boolean)">

      setLocalOnly</a> method.

    </p>

      the watch app may not be installed on all of them.

    </p>

    <p>

      Thus, if bridging should be prevented when the watch app

      is installed, use the <a href=

      "#preventing_bridging_with_the_bridging_mode_feature">Bridging mode

      feature</a>.

    </p>

    <h2 id="using_a_dismissal_id_to_sync_notification_dismissals">

      Using a Dismissal ID to Sync Notification Dismissals

      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=

      "{@docRoot}reference/android/support/v4/app/NotificationCompat.WearableExtender.html">

      "http://developer.android.com/reference/android/support/v4/app/NotificationCompat.WearableExtender.html">

      NotificationCompat.WearableExtender</a> class enable you to use dismissal

      IDs:

    </p>

    <pre>

NotificationCompat.WearableExtender wearableExtender =

new NotificationCompat.WearableExtender().setDismissalId(“abc123”);

new NotificationCompat.WearableExtender().setDismissalId("abc123");

Notification notification = new NotificationCompat.Builder(context)

<set other fields>

.extend(wearableExtender)