Push payload
The data the server sends to devices through FCM, and how the app reads it.
This is the contract between the server's FCM sender and the Android receiver. It is defined as PushData in packages/contract/src/push.ts.
Constraints from FCM
- Every value in
datais a string. Numbers, booleans and lists are encoded. - The whole message must stay under 4,096 bytes (
FCM_MAX_PAYLOAD_BYTES). - Data messages can be delayed or dropped by Android's battery rules, so the inbox in the app, which is loaded from the API, is the real record. The push is only a hint.
message
{
"v": "2",
"kind": "message",
"id": "msg_01jd8x5k2m9q7r4t6v8w0y3z5a",
"project": "ci",
"projectId": "prj_01jd8x5k2m9q7r4t6v8w0y3z5b",
"conversationKey": "c:ci",
"title": "main build failed",
"body": "3 tests failed in auth.spec.ts",
"priority": "5",
"tags": "ci,failure",
"clickUrl": "https://github.com/acme/app/actions/runs/123",
"actions": "[{\"type\":\"view\",\"key\":\"0\",\"label\":\"Open logs\",\"url\":\"https://ci.example.com/runs/123\",\"clear\":false}]",
"attachment": "",
"conversationId": "ci",
"conversationTitle": "",
"conversationIcon": "",
"senderId": "github-actions",
"senderName": "GitHub Actions",
"senderIcon": "",
"truncated": "0",
"createdAt": "1795176000000"
}| Key | Encoding |
|---|---|
v | Payload version (PUSH_VERSION), now "2". The app drops a push whose version it does not know instead of guessing at its fields; the message is still in the inbox. Version "2" names the message by project, projectId and conversationKey, so an app build that only reads "1" ignores it. |
project, projectId | The project's name and id |
conversationKey | The message's thread: c:<feature slug>, or p:<projectId> for the project-level thread (a message sent without a feature). With projectId it is the tap target, notifier://conversation/<projectId>/<conversationKey> |
priority | "1" to "5" |
tags | Comma-separated, "" when empty |
clickUrl, attachment | "" when not set; attachment is the file name. clickUrl is not the tap target (a tap opens the thread): the app shows it as an Open action on the notification and an Open button on the message in the thread |
conversation*, sender* | Flattened conversation and sender; each "" when not set |
actions | JSON string of the stored actions, or "" |
createdAt | Unix milliseconds |
truncated | "1" when something was cut to fit |
Fitting into 4 KB
The sender fills fields in this order and stops adding once the next field would go over the limit:
v,kind,id,project,projectId,conversationKey,priority,createdAt,truncated(always sent)titleconversationId,conversationTitle,senderId,senderNamebody, cut to 1,000 characters (PUSH_BODY_MAX)actions, all or nothingtags,clickUrl,attachment,conversationIcon,senderIcon
The size is measured on the JSON-encoded data object as UTF-8. If the body does not fit in the space that is left, it is cut further to fit, always on a whole character (grapheme), and nothing after it is added.
If anything was cut or left out, truncated is "1". The app then shows what it has right away and calls messages.get to fill in the rest. If that fails, it posts the notification without actions.
dismiss
Decided The server sends it. Handling it on Android is still to be built in the push module.
{ "v": "2", "kind": "dismiss", "ids": "msg_01jd8x5k...,msg_01jd8x6m..." }When someone reads messages on one device, the server sends dismiss to their devices. Those devices then cancel the matching notifications, so the same alert does not have to be cleared on every phone. ids holds only the messages that were newly marked as read. When the list would go over 4,096 bytes, it is split into several dismiss pushes.