Skip to content

Commit 2cb56fb

Browse files
committed
Annotations: tweak annotations publish section
Removed 'Publishing individual annotation events' section separate from 'annotation publish', I think that's confusing. Just mentioned that you can specify a data payload at the bottom of the publish section.
1 parent 298a0ef commit 2cb56fb

File tree

1 file changed

+7
-27
lines changed

1 file changed

+7
-27
lines changed

src/pages/docs/messages/annotations.mdx

Lines changed: 7 additions & 27 deletions
Original file line numberDiff line numberDiff line change
@@ -170,7 +170,7 @@ To publish an annotation for a message, use the `annotations.publish()` method o
170170

171171
The `clientId` specified in the [client options](/docs/api/realtime-sdk#client-options) will be associated with the published annotation. Note that certain annotation types require the client to be identified with a `clientId` in order to publish annotations.
172172

173-
Specify the [annotation type](#annotation-types) using the `type` field of the annotation object, and optionally specify a `name` for the annotation. The `name` is used to aggregate certain annotations when producing an [annotation summary](#annotation-summaries).
173+
Specify the [annotation type](#annotation-types) using the `type` field of the annotation object.
174174

175175
<Code>
176176
```javascript
@@ -218,7 +218,9 @@ await channel.annotations.publish(message.serial, {
218218
```
219219
</Code>
220220

221-
When using `multiple.v1`, you can optionally specify a `count` by which to increment a client's contribution to the summary:
221+
In the case of the `distinct`, `unique`, or `multiple` aggregation types, you should also specify a `name`. For these types, each different name will be aggregated separately in the [annotation summary](#annotation-summaries).
222+
223+
In the case of the `multiple` aggregation type, you should specify both a `name` and a `count`, by which to increment a client's contribution to the summary.
222224

223225
<Code>
224226
```javascript
@@ -238,6 +240,8 @@ await channel.annotations.publish(message.serial, {
238240
```
239241
</Code>
240242

243+
You can additionally specify a `data` payload when publishing an annotation. This is not included in an annotation summary, so only readably by someone [subscribing to individual annotation events](#individual-annotations).
244+
241245
## Delete annotations <a id="delete" />
242246

243247
To delete an annotation, use the `annotations.delete()` method on a channel. Pass in either a [message](/docs/messages) instance or the `serial` of the message to annotate. This method will publish an annotation message with an action of `annotation.delete`.
@@ -388,36 +392,12 @@ The summary will be included in the message's `summary` field, which is an objec
388392
```
389393
</Code>
390394

391-
## Individual annotation events <a id="individual-annotations"/>
395+
## Subscribe to individual annotation events <a id="individual-annotations"/>
392396

393397
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.
394398

395399
Individual events can be useful for activity feeds or detailed logging, however annotation summaries are generally more reliable and efficient for maintaining UI state.
396400

397-
### Publish individual annotation events <a id="publish-individual-annotations"/>
398-
399-
Publishing annotations is the [same as for summaries](#publish). The only difference is that you can additionally specify a `data` payload when publishing an annotation, which isn't included in an annotation summary.
400-
401-
<Code>
402-
```javascript
403-
await channel.annotations.publish(message.serial, {
404-
type: 'receipts:flag.v1',
405-
name: 'delivered',
406-
data: 'Message delivered!'
407-
});
408-
```
409-
410-
```nodejs
411-
await channel.annotations.publish(message.serial, {
412-
type: 'receipts:flag.v1',
413-
name: 'delivered',
414-
data: 'Message delivered!'
415-
});
416-
```
417-
</Code>
418-
419-
### Subscribe to individual annotations <a id="subscribe-individual-annotations"/>
420-
421401
Subscribe to individual annotation events using the `annotations.subscribe()` method on a channel. To subscribe to individual annotations, you must request the `ANNOTATION_SUBSCRIBE` [mode](/docs/channels/options#modes).
422402

423403
<Aside data-type='note'>

0 commit comments

Comments
 (0)