Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

chat: Some clarifications around presence data #257

Open
wants to merge 5 commits into
base: main
Choose a base branch
from
Open

chat: Some clarifications around presence data #257

Changes from all commits
Commits
Show all changes
5 commits
Select commit Hold shift + click to select a range
99f3da5
chat: Remove curly braces in presence data example
lawrence-forooghian Dec 11, 2024
5d4dbb9
chat: Be clearer about what type user can pass as presence data
lawrence-forooghian Dec 11, 2024
50b7c41
chat: Reference spec for presence data
lawrence-forooghian Dec 11, 2024
13a8df2
chat: Clarify that you can pass data when leaving presence
lawrence-forooghian Dec 11, 2024
aa22f1e
chat: Specify how to handle presence operation without custom data
lawrence-forooghian Dec 11, 2024
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
13 changes: 6 additions & 7 deletions textile/chat-features.textile
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -340,16 +340,15 @@ Presence allows chat room users to indicate to others that they're online, as we

* @(CHA-PR1)@ Presence for a Room is exposed on the realtime channel used for chat messages, in the format @<roomId>::$chat::$chatMessages@. For example, if your room id is @my-room@ then the presence channel will be @my-room::$chat::$chatMessages@.
* @(CHA-PR2)@ The presence payload for Chat is opinionated, so that we may add or change fields later without needing to consider how customers are using presence.
** @(CHA-PR2a)@ @[Testable]@ The presence data format is a JSON object as described below. Customers may specify content of an arbitrary type to be placed in the @userCustomData@ field.
** @(CHA-PR2a)@ @[Testable]@ The presence data format is a JSON object as described below. Customers may specify an arbitrary "JSON @value@":https://www.json.org to be placed in the @userCustomData@ field.

<pre>
{
"userCustomData": {
// Some user specified type, does not have to be object.
}
"userCustomData": // Any JSON `value`, does not have to be `object`. This field may be absent; see CHA-PR2b.
}
</pre>

** @(CHA-PR2b)@ @[Testable]@ If the user performs a presence operation (@CHA-PR3a@, @CHA-PR10a@, or @CHA-PR4a@) without providing any custom data (which, for the sake of clarity, we emphasise is _not_ the same as providing the JSON @value@ of @null@ as custom data, which is handled like any other JSON @value@ per @CHA-PR2a@), then the @userCustomData@ field must be omitted from the @CHA-PR2a@ presence data that gets sent.
* @(CHA-PR3)@ Users may enter presence. The behaviour depends on the current room status, as presence operations in a Realtime Client cause implicit attaches.
** @(CHA-PR3a)@ @[Testable]@ Users may choose to enter presence, optionally providing custom data to enter with. The overall presence data must retain the format specified in @CHA-PR2@.
** @(CHA-PR3b)@ This clause has been replaced by @CHA-PR3c - CHA-PR3g@.
Expand All @@ -373,7 +372,7 @@ Presence allows chat room users to indicate to others that they're online, as we
** @(CHA-PR10f)@ This specification point has been removed. It was superseded by @CHA-PR10h@.
** @(CHA-PR10g)@ This specification point has been removed. It was superseded by @CHA-PR10h@.
* @(CHA-PR4)@ Users may leave presence.
** @(CHA-PR4a)@ @[Testable]@ Users may choose to leave presence, which results in them being removed from the Realtime presence set.
** @(CHA-PR4a)@ @[Testable]@ Users may choose to leave presence, which results in them being removed from the Realtime presence set. The user may optionally provide custom data to leave with. The overall presence data must retain the format specified in @CHA-PR2@.
* @(CHA-PR5)@ @[Testable]@ It must be possible to query if a given clientId is in the presence set.
* @(CHA-PR6)@ @[Testable]@ It must be possible to retrieve all the "@Members":#chat-structs-presence-member of the presence set. The behaviour depends on the current room status, as presence operations in a Realtime Client cause implicit attaches.
** @(CHA-PR6a)@ This clause has been replaced by @CHA-PR6b - CHA-PR6f@.
Expand Down Expand Up @@ -887,7 +886,7 @@ h3(#chat-structs-presence-member). Presence Member
"clientId": "who-sent-the-message",
"action": "enter",
"updatedAt": DateTime(),
"data": {}, // Whatever the user-provided data is. It must be destructured from the internal format we use.
"data": { … }, // A presence data object containing any user-provided data. The structure of this object is described by CHA-PR2.
"extras": {
"headers": {
"baz": "qux"
Expand All @@ -903,7 +902,7 @@ h3(#chat-structs-presence-event). Presence Event
"clientId": "who-is-in-presence",
"action": "enter",
"timestamp": DateTime(),
"data": {}, // Whatever the user-provided data is. It must be destructured from the internal format we use.
"data": { … }, // A presence data object containing any user-provided data. The structure of this object is described by CHA-PR2.
}
</pre>

Expand Down
Loading