From 1c3bccceb2a3e922998eb976f1c071e2f75893c1 Mon Sep 17 00:00:00 2001 From: Bert McMeen Date: Fri, 2 Sep 2016 10:33:03 -0700 Subject: [PATCH] Docs: Preview 3 - Update to bridging of notifications Bug: 31181082 Change-Id: Id7c77de123b709e218f62ead30a3429d5ec31430 --- docs/html/wear/preview/features/bridger.jd | 230 +++++++++++++++++---- 1 file changed, 195 insertions(+), 35 deletions(-) diff --git a/docs/html/wear/preview/features/bridger.jd b/docs/html/wear/preview/features/bridger.jd index b7be093ed2987..2d879caeccc2e 100644 --- a/docs/html/wear/preview/features/bridger.jd +++ b/docs/html/wear/preview/features/bridger.jd @@ -6,19 +6,26 @@ page.tags="wear-preview"
-
    +
+
  • + Existing Method of Preventing Bridging +
    • + +
  • + Using a Dismissal ID to Sync Notification Dismissals +
    • +
    @@ -27,19 +34,20 @@ page.tags="wear-preview" "{@docRoot}training/wearables/notifications/index.html">are bridged (shared) 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.

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

    -

    - Preventing Bridging with the Bridging Mode Feature +

    + Specifying a Bridging Configuration in the Manifest File

    - 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 + <meta-data> entry in the manifest file of the watch app (e.g. the standalone watch app), as follows:

    - 
    +
     com.google.android.wearable.notificationBridgeMode
-    
    
+

    Setting that entry to NO_BRIDGING will prevent bridging:

    - 
    -<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" />
 
    
+
     
    
-      The default bridging behavior occurs if you do not include the entry or
+      The default bridging behavior occurs if you do not
+      include the <meta-data> entry or
       if you specify a value of BRIDGING instead of
       NO_BRIDGING.
     
    
 
-    
    
-      Existing method of preventing bridging
+    
    
+      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.
+    
    
+
+    
    
+      The bridging configuration that is set in the manifest takes effect as
+      soon as a watch app is installed.
+    
    
+
+    
    
+      Specifying a Bridging Configuration at Runtime
+    
    
+
+    
    
+      This section describes how to specify a bridging configuration at runtime
+      using the BridgingManager class
+      (android.support.wearable.notifications.BridgingManager).
+    
    
+
+    
    
+      You can set a bridging mode, and optionally set tags for notifications
+      that are exempt from the bridging mode, using a
+      BridgingManager object. Specifically, create a
+      BridgingConfig object and set it as shown in this section,
+      optionally using the setBridgingEnabled method. If you
+      specify a bridging configuration at runtime, then if the
+      setBridgingEnabled method is not set, bridging is enabled by
+      default.
+    
    
+
+    
    
+      Specifying a bridging configuration at runtime overrides a
+      bridging-related setting in the Android manifest file.
+    
    
+
+    
    
+      Disable bridging for all notifications
     
    
 
+    
    
+      You can use the setBridgingEnabled method, as follows:
+    
    
+
+
    +BridgingManager.setConfig(context,
+  new BridgingConfig.Builder(context)
+    .setBridgingEnabled(false)
+    .build());
+
    
+    
    
+      If the above setter is not called, the bridging mode defaults to true.
+      Here is an example of setting tags without using the
+      setBridgingEnabled method, excluding notifications with a
+      tag of foo or bar:
+    
    
+
+
    +BridgingManager.setConfig(context,
+  new BridgingConfig.Builder(context)
+    .addExcludedTag("foo")
+    .addExcludedTag("bar")
+    .build());
+
    
+    
    
+      Exempt notifications that are tagged
+    
    
+
+    
    
+      You can disable bridging for all notifications except those with certain
+      tags.
+    
    
+
+    
    
+      For example, you can disable bridging, except for notifications tagged as
+      foo or bar, with the following:
+    
    
+
+
    +BridgingManager.setConfig(context,
+  new BridgingConfig.Builder(context)
+    .setBridgingEnabled(false)
+    .addExcludedTag("foo")
+    .addExcludedTag("bar")
+    .build());
+
    
+
+    
    
+      As another example, you can disable bridging for all notifications except
+      for notifications tagged as foo, bar or
+      baz.
+    
    
+
+    
    +BridgingManager.setConfig(context,
+  new BridgingConfig.Builder(context)
+    .setBridgingEnabled(false)
+    .addExcludedTags(Arrays.asList("foo", "bar", "baz"))
+    .build());
+
    
+    
    
+      Enable bridging except for notifications with certain tags
+    
    
+
+    
    
+      You can enable bridging for all notifications except those with certain
+      tags.
+    
    
+
+    
    
+      For example, you can enable bridging for all notifications, except for
+      notifications tagged as foo or bar, with the
+      following:
+    
    
+
+
    +BridgingManager.setConfig(context,
+  new BridgingConfig.Builder(context)
+    .setBridgingEnabled(true)
+    .addExcludedTag("foo")
+    .addExcludedTag("bar")
+    .build());
+
    
+
+    
    
+      Setting a bridge tag
+    
    
+
+    
    
+      A bridge tag can be set on a notification by calling the
+      setNotificationBridgeTag method as follows:
+    
    
+
+
    +BridgingManager.setNotificationBridgeTag(<NotificationCompat.Builder>, <String>);
+
    
+
+    
    
+      For example:
+    
    
+
+
    +NotificationCompat.Builder builder = new NotificationCompat.Builder(context)
+<set other fields>;
+BridgingManager.setNotificationBridgeTag(builder, "foo");
+Notification notification =  builder.build();
+
    
+
+    
    
+      Existing Method of Preventing Bridging
+    
    
+
     
    
       An existing way to prevent bridging is with the
       Notification.Builder class; specify true in the
       
+      "http://developer.android.com/reference/android/app/Notification.Builder.html#setLocalOnly(boolean)">
       setLocalOnly method.
     
    
 
@@ -95,12 +261,6 @@ com.google.android.wearable.notificationBridgeMode
       the watch app may not be installed on all of them.
     
    
 
-    
    
-      Thus, if bridging should be prevented when the watch app
-      is installed, use the Bridging mode
-      feature.
-    
    
 
     
    
       Using a Dismissal ID to Sync Notification Dismissals
@@ -110,7 +270,7 @@ com.google.android.wearable.notificationBridgeMode
       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 
+      "http://developer.android.com/reference/android/support/v4/app/NotificationCompat.WearableExtender.html">
       NotificationCompat.WearableExtender class enable you to use dismissal
       IDs:
     
    
@@ -118,7 +278,7 @@ com.google.android.wearable.notificationBridgeMode
     
     public WearableExtender setDismissalId(String dismissalId)
 public String getDismissalId()
-    
    
+

    To enable a dismissal to be synced, use the setDismissalId() method. For each notification, pass a globally unique ID, as a string, @@ -135,12 +295,12 @@ public String getDismissalId() 

     NotificationCompat.WearableExtender wearableExtender =
-new NotificationCompat.WearableExtender().setDismissalId(“abc123”);
+new NotificationCompat.WearableExtender().setDismissalId("abc123");
 Notification notification = new NotificationCompat.Builder(context)
 <set other fields>
 .extend(wearableExtender)
 .build();
-
    +

    Dismissal IDs work if a watch is paired to an Android phone, but not if a watch is paired to an iPhone.