Listening to Events - Socketo Docs

Event Binding Mechanics

Clients can register event listeners at three distinct scoping levels:

1. Channel-Level Binding

Listens for broadcasts dispatched to a specific channel:

const channel = pusher.subscribe('orders')

// Bind callback to specific event
channel.bind('order-created', (data: { orderId: string }) => {
  console.log('Order created:', data.orderId)
})

// Unbind a specific listener callback
channel.unbind('order-created', callbackFn)

// Unbind all callbacks for an event
channel.unbind('order-created')

// Unbind all callbacks on the channel
channel.unbind_all()

2. Global Connection Binding

Interprets all incoming events across all subscribed channels on the socket connection:

pusher.bind_global((eventName: string, data: any) => {
  console.log(`Global event [${eventName}]:`, data)
})

3. User-Level Binding

Listens for user-targeted broadcasts dispatched via pusher.sendToUser(...). Requires prior connection-level authentication via pusher.signin():

pusher.signin()

pusher.user.bind('notification', (payload: { title: string }) => {
  console.log('User notification:', payload.title)
})

Protocol Wire Frames vs SDK Events

Socketo distinguishes between raw WebSocket frames exchanged over the wire and client SDK synthesized events:

Event Name	Level	Description	Payload Structure
`pusher:connection_established`	Wire & SDK	Connection handshake successful	`{ socket_id, activity_timeout }`
`pusher_internal:subscription_succeeded`	Wire	Channel subscription accepted	`{}` or presence roster object
`pusher:subscription_succeeded`	SDK	Client notification of subscription	Initial channel metadata
`pusher:subscription_error`	SDK	Channel subscription rejected	`{ error, status }`
`pusher_internal:member_added`	Wire	Presence member joined	`{ user_id, user_info }`
`pusher:member_added`	SDK	Presence member joined	Member object
`pusher_internal:member_removed`	Wire	Presence member vacated	`{ user_id }`
`pusher:member_removed`	SDK	Presence member vacated	Member object
`pusher:ping` / `pusher:pong`	Wire	Heartbeat liveness probe	`{}`
`pusher:error`	Wire & SDK	Protocol or edge policy error	`{ code, message }`

Protocol Error Structure

When a protocol violation or rate limit is reached, Socketo transmits a pusher:error event:

json

{
  "event": "pusher:error",
  "data": {
    "code": 4301,
    "message": "Rate limit exceeded"
  }
}

pusher.bind('pusher:error', (err: { code: number; message: string }) => {
  console.error(`Socketo Protocol Error [${err.code}]: ${err.message}`)
})

Event Binding Mechanics#

1. Channel-Level Binding#

2. Global Connection Binding#

3. User-Level Binding#

Protocol Wire Frames vs SDK Events#