realtime/presence

51 notes, read out of this brain and free to use. Each one was extracted from a source and is re-checked against its exam.

Presence use cases

Presence is used for showing who is online and tracking active participants.

Presence messages have extension value 'presence' in realtime.messages

The extension field on the realtime.messages table records the message type. For Presence messages, the value of realtime.messages.extension is 'presence'. You can check for this value in your RLS policies.

Example: RLS policy to allow sending presence messages on topic

```sql create policy "authenticated can track presence on topic" on "realtime"."messages" for insert to authenticated with check ( exists ( select user_id from rooms_users where user_id = (select auth.uid()) and room_topic = (select realtime.topic()) and realtime.messages.extension in ('presence') ) ); ``` This policy allows authenticated users who are linked to the requested topic to update their presence status.

Realtime limits by plan - presence keys per object

Presence keys per object limits are: Free 10, Pro 10, Pro (no spend cap) 10, Team 10, Enterprise 10+.

Realtime limits by plan - presence messages per second

Presence messages per second limits are: Free 20, Pro 50, Pro (no spend cap) 1,000, Team 1,000, Enterprise 1,000+.

Realtime limits by plan - presence calls per client per 30 seconds

Presence calls per client per 30 seconds limit is 5 for all plans: Free 5, Pro 5, Pro (no spend cap) 5, Team 5, Enterprise 5.

Supabase Presence for tracking online users

Supabase Presence can be used to display currently online users in a Flutter application. It makes it easy to track users joining and leaving a session for collaborative applications.

Max presence events per second setting

The 'Max presence events per second' setting determines the maximum number of presence events per second that can be sent through Realtime.

Presence: share state between users overview

Presence in Supabase Realtime lets each connected client publish a small piece of state called a 'presence payload' to a shared channel. Supabase stores each client's payload under a unique presence key and keeps a merged view of all connected clients.

Presence events: sync, join, leave

When any client subscribes, disconnects, or updates their presence payload, Supabase triggers one of three events: sync (the full presence state has been updated), join (a new client has started tracking presence), or leave (a client has stopped tracking presence).

Presence not designed for high-frequency updates

Presence syncs state through the server and notifies all subscribers on every change. Calling track() rapidly—for example on every mouse move to share cursor positions—will flood the channel and cause performance problems. For high-frequency or fire-and-forget updates, use Broadcast instead. Presence is best suited for slow-changing state such as online/offline status, active document, or current page.

Sync event behavior: join and leave during reconciliation

During a sync event, you may receive join and leave events simultaneously, even though no users are joining or leaving. This is expected behavior—Presence reconciles its local state with the server state, which can trigger these events as part of the synchronization process. This reflects state reconciliation, not real user movement.

Presence state structure example

The complete presence state returned by presenceState() looks like this: {"client_key_1": [{"userId": 1, "typing": false}], "client_key_2": [{"userId": 2, "typing": true}]}

JavaScript: subscribe to presence sync, join, leave events

Example showing how to listen to presence events in JavaScript: ```js import { createClient } from '@supabase/supabase-js' const supabase = createClient('your_project_url', 'your_supabase_api_key') const roomOne = supabase.channel('room_01') roomOne .on('presence', { event: 'sync' }, () => { const newState = roomOne.presenceState() console.log('sync', newState) }) .on('presence', { event: 'join' }, ({ key, newPresences }) => { console.log('join', key, newPresences) }) .on('presence', { event: 'leave' }, ({ key, leftPresences }) => { console.log('leave', key, leftPresences) }) .subscribe() ```

Dart: subscribe to presence sync, join, leave events

Example showing how to listen to presence events in Dart: ```dart final supabase = Supabase.instance.client; final roomOne = supabase.channel('room_01'); roomOne.onPresenceSync((_) { final newState = roomOne.presenceState(); print('sync: $newState'); }).onPresenceJoin((payload) { print('join: $payload'); }).onPresenceLeave((payload) { print('leave: $payload'); }).subscribe(); ```

Swift: subscribe to presence change stream

Example showing how to listen to presence events in Swift: ```swift let roomOne = await supabase.channel("room_01") let presenceStream = await roomOne.presenceChange() await roomOne.subscribe() for await presence in presenceStream { print(presence.join) // You can also use presence.decodeJoins(as: MyType.self) print(presence.leaves) // You can also use presence.decodeLeaves(as: MyType.self) } ```

Kotlin: subscribe to presence change flow

Example showing how to listen to presence events in Kotlin: ```kotlin val roomOne = supabase.channel("room_01") val presenceFlow: Flow<PresenceAction> = roomOne.presenceChangeFlow() presenceFlow .onEach { println(it.joins) //You can also use it.decodeJoinsAs<YourType>() println(it.leaves) //You can also use it.decodeLeavesAs<YourType>() } .launchIn(yourCoroutineScope) //You can also use .collect { } here roomOne.subscribe() ```

Python: subscribe to presence sync, join, leave events

Example showing how to listen to presence events in Python: ```python room_one = supabase.channel('room_01') room_one .on_presence_sync(lambda: print('sync', room_one.presenceState())) .on_presence_join(lambda key, curr_presences, joined_presences: print('join', key, curr_presences, joined_presences)) .on_presence_leave(lambda key, curr_presences, left_presences: print('leave', key, curr_presences, left_presences)) .subscribe() ```

C#: subscribe to presence Sync, Join, Leave events

Example showing how to listen to presence events in C#: ```c# class UserStatus : BasePresence { [JsonProperty("user")] public string User { get; set; } [JsonProperty("online_at")] public string OnlineAt { get; set; } } var roomOne = supabase.Realtime.Channel("room_01"); var presence = roomOne.Register<UserStatus>(Guid.NewGuid().ToString()); presence.AddPresenceEventHandler(EventType.Sync, (sender, type) => { Console.WriteLine($"sync: {presence.CurrentState}"); }); presence.AddPresenceEventHandler(EventType.Join, (sender, type) => Console.WriteLine("join")); presence.AddPresenceEventHandler(EventType.Leave, (sender, type) => Console.WriteLine("leave")); await roomOne.Subscribe(); ```

Kotlin: set custom presence key

Example showing how to set a custom presence key in Kotlin: ```kotlin val channelC = supabase.channel("test") { presence { key = "userId-123" } } ```

JavaScript: send presence state with track()

Example showing how to send presence state in JavaScript: ```js import { createClient } from '@supabase/supabase-js' const supabase = createClient('your_project_url', 'your_supabase_api_key') const roomOne = supabase.channel('room_01') const userStatus = { user: 'user-1', online_at: new Date().toISOString(), } roomOne.subscribe(async (status) => { if (status !== 'SUBSCRIBED') { return } const presenceTrackStatus = await roomOne.track(userStatus) console.log(presenceTrackStatus) }) ```

Dart: send presence state with track()

Example showing how to send presence state in Dart: ```dart final roomOne = supabase.channel('room_01'); final userStatus = { 'user': 'user-1', 'online_at': DateTime.now().toIso8601String(), }; roomOne.subscribe((status, error) async { if (status != RealtimeSubscribeStatus.subscribed) return; final presenceTrackStatus = await roomOne.track(userStatus); print(presenceTrackStatus); }); ```

Swift: send presence state with track()

Example showing how to send presence state in Swift: ```swift let roomOne = await supabase.channel("room_01") // Using a custom type let userStatus = UserStatus( user: "user-1", onlineAt: Date().timeIntervalSince1970 ) await roomOne.subscribe() try await roomOne.track(userStatus) // Or using a raw JSONObject. await roomOne.track( [ "user": .string("user-1"), "onlineAt": .double(Date().timeIntervalSince1970) ] ) ```

Kotlin: send presence state with track()

Example showing how to send presence state in Kotlin: ```kotlin val roomOne = supabase.channel("room_01") val userStatus = UserStatus( //Your custom class user = "user-1", onlineAt = Clock.System.now().toEpochMilliseconds() ) roomOne.subscribe(blockUntilSubscribed = true) //You can also use the roomOne.status flow instead, but this parameter will block the coroutine until the status is joined. roomOne.track(userStatus) ```

Python: send presence state with track()

Example showing how to send presence state in Python: ```python room_one = supabase.channel('room_01') user_status = { "user": 'user-1', "online_at": datetime.datetime.now().isoformat(), } def on_subscribe(status, err): if status != RealtimeSubscribeStates.SUBSCRIBED: return room_one.track(user_status) room_one.subscribe(on_subscribe) ```

C#: send presence state with Track()

Example showing how to send presence state in C#: ```c# var roomOne = supabase.Realtime.Channel("room_01"); var presence = roomOne.Register<UserStatus>(Guid.NewGuid().ToString()); await roomOne.Subscribe(); await presence.Track(new UserStatus { User = "user-1", OnlineAt = DateTime.UtcNow.ToString("o") }); ```

Presence: client receives state from other subscribed clients

A client will receive state from any other client that is subscribed to the same topic. It will also automatically trigger its own sync and join event handlers.

Stop tracking presence with untrack()

You can stop tracking presence using the untrack() method. This will trigger the sync and leave event handlers.

JavaScript: stop tracking presence with untrack()

Example showing how to stop tracking presence in JavaScript: ```js import { createClient } from '@supabase/supabase-js' const supabase = createClient('your_project_url', 'your_supabase_api_key') const roomOne = supabase.channel('room_01') const untrackPresence = async () => { const presenceUntrackStatus = await roomOne.untrack() console.log(presenceUntrackStatus) } untrackPresence() ```

Dart: stop tracking presence with untrack()

Example showing how to stop tracking presence in Dart: ```dart final roomOne = supabase.channel('room_01'); untrackPresence() async { final presenceUntrackStatus = await roomOne.untrack(); print(presenceUntrackStatus); } untrackPresence(); ```

Swift: stop tracking presence with untrack()

Example showing how to stop tracking presence in Swift: ```swift await roomOne.untrack() ```

Kotlin: stop tracking presence with untrack()

Example showing how to stop tracking presence in Kotlin: ```kotlin suspend fun untrackPresence() { roomOne.untrack() } untrackPresence() ```

Python: stop tracking presence with untrack()

Example showing how to stop tracking presence in Python: ```python room_one.untrack() ```

C#: stop tracking presence with Untrack()

Example showing how to stop tracking presence in C#: ```c# await presence.Untrack(); ```

Presence key configuration

By default, Presence will generate a unique UUIDv1 key on the server to track a client channel's state. If you prefer, you can provide a custom key when creating the channel. This key should be unique among clients.

JavaScript: set custom presence key

Example showing how to set a custom presence key in JavaScript: ```js import { createClient } from '@supabase/supabase-js' const supabase = createClient('SUPABASE_URL', 'SUPABASE_PUBLISHABLE_KEY') const channelC = supabase.channel('test', { config: { presence: { key: 'userId-123', }, }, }) ```

Dart: set custom presence key

Example showing how to set a custom presence key in Dart: ```dart final channelC = supabase.channel( 'test', opts: const RealtimeChannelConfig(key: 'userId-123'), ); ```

Swift: set custom presence key

Example showing how to set a custom presence key in Swift: ```swift let channelC = await supabase.channel("test") { $0.presence.key = "userId-123" } ```

Python: set custom presence key

Example showing how to set a custom presence key in Python: ```python channel_c = supabase.channel('test', { "config": { "presence": { "key": 'userId-123', }, }, }) ```

C#: set custom presence key

Example showing how to set a custom presence key in C#: ```c# var channelC = supabase.Realtime.Channel("test"); var presence = channelC.Register<UserStatus>("userId-123"); ```

Presence Events report

The Presence Events report monitors the volume of presence state updates sent through Realtime channels over time. Presence events occur when clients track, update, or untrack their presence state in a channel, triggering sync, join, or leave events. Unlike broadcast messages, presence state is persisted in the channel so new joiners immediately receive the current state without waiting for other users to send updates. Essential for understanding how application tracks and synchronizes shared state between users. Available for all plans.

Presence message rate limits by plan

Presence messages per second limits vary by plan: Free plan allows 20 messages per second, Pro plan allows 50 messages per second, Pro no spend cap allows 1,000 messages per second, Team plan allows 1,000 messages per second, and Enterprise plan allows 1,000 messages per second.

Presence keys per object limit

Presence keys per object limit is 10 for most plans.

Presence configuration options

Presence config in phx_join contains: `enabled` (boolean to enable/disable presence tracking) and `key` (string for presence key, if not specified or empty a UUID will be generated and used).

Presence event structure

Presence event is sent after joining a channel to send presence metadata. The payload contains: `type` ('presence'), `event` ('track'), and `payload` (JSON object with user metadata like name, color, etc). This metadata is sent back to all clients via presence_state and presence_diff events.

Presence state server message

presence_state message sent after joining contains: key-value pairs where key is client key (UUID if not specified), value is object with `metas` array. Each meta contains `phx_ref` (unique reference ID) and any custom fields sent by client (e.g., name, color).

Presence diff server message

presence_diff message contains: `joins` object (clients joining with their metas) and `leaves` object (clients leaving with their metas). Each contains key-value pairs where key is client key and value has `metas` array with `phx_ref` and custom fields.

Presence errors

Presence push replies surface payload-shape errors with reason: 'Presence track payload must be a map'. Other push-level failures (RLS write denied, unknown event type, internal errors) return status 'error' with no reason field. Presence rate-limit and size violations arrive as channel-level system errors and close the channel.

Presence event example in protocol 2.0.0

Example presence message in protocol 2.0.0: ['1', '5', 'realtime:presence-room', 'presence', { 'type': 'presence', 'event': 'track', 'payload': { 'name': 'Alice', 'color': 'hsl(29, 100%, 70%)' } }]

Presence state example in protocol 2.0.0

Example presence_state message showing multiple clients: ['4', null, 'realtime:cursor-room', 'presence_state', { '2wCojG1xWgxG2ZxwocvSX': { 'metas': [{ 'phx_ref': 'GHlA1fShRjMmZhnL', 'color': 'hsl(204, 100%, 70%)', 'key': '2wCojG1xWgxG2ZxwocvSX' }] }, '6eorYR7andHiq-7tCkmxQ': { 'metas': [{ 'phx_ref': 'GHk99Q_ez6-GzaeG', 'color': 'hsl(7, 100%, 70%)', 'key': '6eorYR7andHiq-7tCkmxQ' }] } }]

Presence diff example in protocol 2.0.0

Example presence_diff message: [null, null, 'realtime:cursor-room', 'presence_diff', { 'joins': { 'XnAJXkZVEJuBYZcp9GCG5': { 'metas': [{ 'phx_ref': 'GHlE8VLvxuKGzQJN', 'color': 'hsl(60, 100%, 70%)', 'user': '123' }] } }, 'leaves': { 'ouCsaiOdKZ9yauoy4x5pv': { 'metas': [{ 'phx_ref': 'GHlE8HyhSPAmZgdB', 'color': 'hsl(72, 100%, 70%)', 'user': '456' }] } } }]

Give your agent this brain