Real Time Updates (SSE and Push Notifications)

---

At Level 6, the client is maintains the user interface in sync with server‑side changes. In earlier integration levels, the Client Back-End SDK performs this task automatically. Without that layer, you must listen for real‑time update notifications and respond by refreshing the page or specific screen sections. This action occurs through server‑sent events (SSE) on the web and push notifications on native platforms.

=--

System Overview

Real-time updates maintain user interface state when server-side information changes.
The Level 6 integration layer performs this task without assistance from the Client Back-End SDK.
The client receives update messages through SSE on web platforms and push notifications on mobile platforms.

Real-Time Message
      ↓
Inspect components
  Timeout? → Yes → Expire timers
  Endpoint? → Yes → PATCH endpoint
      ↓
Apply patches
      ↓
Maintain poll cycle

---

Quick Reference Table

Platform	Mechanism	Token Required	Notes
Web	Server-Sent Events (SSE)	Yes	Open a long-lived stream and re-open with each login or logout.
Android / iOS	Push Notifications	Yes	Receive a custom data string that follows SSE format.

---

Before You Start

Confirm the following:

• An active access token exists for each connection.
• Patch endpoints exist for all active screens.
• The client expires timers, applies patches, and maintains poll cycles.

Web: Server‑Sent Events (SSE)

On web implementations, the client opens a long‑lived SSE connection to the endpoint in the Open API. The client uses the same access token that authorizes other API calls. The SSE channel streams messages to the client as they occur. When the user logs out or logs in, the client closes the active connection and opens a new connection with the updated token.

Message Format

Update notifications, sent over SSE, arrive as single strings that contain up to two space-separated components.
Each component is optional and defines a specific instruction.

A message follows this structure:

<keyword> <endpoint>

• The keyword may be Timeout.
• The endpoint may be a valid PATCH endpoint.
• Either component may be absent, and both components may appear together.

Timeout Component

If the first component is Timeout:

• The client expires all active patch timers immediately.
• The client requests existing updates by calling the patch endpoint that belongs to the current screen.
• If the Timeout keyword is absent, the client maintains the active timeout schedule.

Endpoint Component

If the second component is an endpoint:

• The client performs a PATCH call to that endpoint to obtain updated data.
• If the endpoint component is absent, the client performs no immediate PATCH call.

Both Components

If a message contains both Timeout and an endpoint, both behaviors apply.
This mechanism enables the server to define immediate refresh actions, targeted updates, or both.

Examples

• Timeout /appointments/123

  • Expire active timers
  • Call PATCH /appointments/123

• Timeout

  • Expire active timers
  • Call the patch endpoint that belongs to the current screen model

• /appointments/123

  • Call PATCH /appointments/123
  • Apply returned updates

• (blank)

  • No component exists
  • No special action is required

Message Interpretation Table

Message	Timeout Instruction	Endpoint Instruction
Timeout /appointments/123	Yes	Yes
Timeout	Yes	No
/appointments/123	No	Yes
(blank)	No	No

Reconnect Logic

If the browser reports a closed SSE connection, the client opens a new stream with the active access token. A network issue or a token change can also close the stream, and the client opens another stream after a short delay.
Each stream uses the current access token.

Air Doctor pages define timeout intervals, so state updates exist even when no SSE stream is active. These updates do not match the frequency that high-activity screens, such as chat, require.

Heartbeats

To prevent idle connections from closing, Air Doctor sends heartbeat messages over SSE when no updates exist. These heartbeats have no special meaning and may contain no content. The client ignores these messages and monitors the stream state. If the browser reports that the stream is closed, the client opens a new SSE connection with the active token.

Mobile: Push Notifications

On mobile platforms, the Air Doctor server sends push notifications, instead of SSE, through the partner backend, which then delivers them to the client application.

Each notification includes:

• Optional user-visible text.
• A custom data string that matches the SSE message structure.

Client Requirements

• Parse the data string.
• Expire timers when the string contains the Timeout keyword.
• PATCH the endpoint when an endpoint appears.
• Include the current push notification token in all Air Doctor API requests.

Air Doctor tracks the user who is active (last active) on the device and sends messages relevant to that user. Because tokens can change dynamically, especially on Android, include the current push notification token in the appropriate header for all calls to Air Doctor servers.

Processing Notifications

The processing model remains identical across platforms.

1. Expire timeouts. If the update message includes the Timeout keyword, the client cancels any pending patch timers so the client refreshes immediately.
2. Invoke patch. If the message contains an endpoint, the client performs a PATCH request to that endpoint immediately and applies the returned patches to the active screen. This call runs alongside the existing polling cycle. No adjustments to the longer polling interval are required.
3. Maintain polling. Keep the regular update intervals active, even when an SSE channel is open. The poll cycle resolves missed events, network interruptions, and token changes.

User modifies screen state
        ↓
Server emits: "Timeout /appointments/123"
        ↓
Client expires timers
        ↓
Client performs PATCH /appointments/123
        ↓
Client applies patches
        ↓
Screen matches server state

Summary

Real‑time updates keep your application in sync with server‑side changes without excessive polling. On the web, open an SSE channel with the current access token. On mobile platforms, the backend forwards push notifications to the client. Each notification may include a Timeout keyword and/or an endpoint, indicating whether to expire timers, call a specific PATCH endpoint, or both. Always re‑establish connections when the user logs in or out and combine notifications with periodic polling to handle missed events. For details on handling patch responses, refer to the PATCH and POST sub‑articles.`