Merge pull request #2871 from ably/clipped-message-annotations

Add clipped flag to annotations doc

Author: vladvelici

src/pages/docs/messages/annotations.mdx

@@ -75,7 +75,8 @@ A given client can contribute to the summary only once per annotation type.
 {
   "reactions:flag.v1": {
     "total": 3,
-    "clientIds": ["client1", "client2", "client3"]
+    "clientIds": ["client1", "client2", "client3"],
+    "clipped": false
   }
 }
 ```
@@ -95,11 +96,13 @@ Deleting an annotation removes the `clientId` from the list of clients that cont
   "categories:distinct.v1": {
     "important": {
       "total": 2,
-      "clientIds": ["client1", "client3"]
+      "clientIds": ["client1", "client3"],
+      "clipped": false
     },
     "urgent": {
       "total": 3,
-      "clientIds": ["client1", "client2", "client3"]
+      "clientIds": ["client1", "client2", "client3"],
+      "clipped": false
     }
   }
 }
@@ -120,11 +123,13 @@ Deleting an annotation removes the `clientId` from the list of clients that cont
   "status:unique.v1": {
     "important": {
       "total": 2,
-      "clientIds": ["client1", "client3"]
+      "clientIds": ["client1", "client3"],
+      "clipped": false
     },
     "urgent": {
       "total": 1,
-      "clientIds": ["client2"]
+      "clientIds": ["client2"],
+      "clipped": false
     }
   }
 }
@@ -151,15 +156,19 @@ Deleting an annotation removes all contributions made by that `clientId` for tha
         "client1": 3,
         "client2": 2
       },
-      "totalUnidentified": 2
+      "totalUnidentified": 2,
+      "clipped": false,
+      "totalClientIds": 2
     },
     "option-b": {
       "total": 4,
       "clientCounts": {
         "client1": 2,
         "client3": 1
       },
-      "totalUnidentified": 1
+      "totalUnidentified": 1,
+      "clipped": false,
+      "totalClientIds": 2
     }
   }
 }
@@ -350,26 +359,31 @@ The summary will be included in a `summary` field nested within the message's `a
   },
   "reactions:flag.v1": {
     "total": 3,
-    "clientIds": ["client1", "client2", "client3"]
+    "clientIds": ["client1", "client2", "client3"],
+    "clipped": false
   },
   "categories:distinct.v1": {
     "important": {
       "total": 2,
-      "clientIds": ["client1", "client3"]
+      "clientIds": ["client1", "client3"],
+      "clipped": false
     },
     "urgent": {
       "total": 3,
-      "clientIds": ["client1", "client2", "client3"]
+      "clientIds": ["client1", "client2", "client3"],
+      "clipped": false
     }
   },
   "status:unique.v1": {
     "important": {
       "total": 2,
-      "clientIds": ["client1", "client3"]
+      "clientIds": ["client1", "client3"],
+      "clipped": false
     },
     "urgent": {
       "total": 1,
-      "clientIds": ["client2"]
+      "clientIds": ["client2"],
+      "clipped": false
     }
   },
   "voting:multiple.v1": {
@@ -379,21 +393,34 @@ The summary will be included in a `summary` field nested within the message's `a
         "client1": 3,
         "client2": 2
       },
-      "totalUnidentified": 2
+      "totalUnidentified": 2,
+      "clipped": false,
+      "totalClientIds": 2
     },
     "option-b": {
       "total": 4,
       "clientCounts": {
         "client1": 2,
         "client3": 1
       },
-      "totalUnidentified": 1
+      "totalUnidentified": 1,
+      "clipped": false,
+      "totalClientIds": 2
     }
   }
 }
 ```
 </Code>
 
+### Large summaries <a id="large-summaries"/>
+
+If many clients publish the same annotation to the same message, the list of client IDs in that annotation summary will get clipped in order to keep the event size within the maximum message size.
+
+When a summary is clipped:
+- The `total` property shows the total number of annotations as expected, but the `clientIds` property will contain only a partial list of client IDs.
+- The `clipped` property is set to `true`.
+- For the `multiple` annotation type, use the `totalClientIds` property to determine the total number of clients that have published the annotation. For the other annotation types this is equal to `total`. 
+
 ## Subscribe to individual annotation events <a id="individual-annotations"/>
 
 It is also possible to subscribe to individual annotation events, rather than annotation summaries. These are the emitted when [publishing](#publish) or [deleting](#delete) an annotation.