DOCS
Ask AI

Monitor and respond to connection status changes

Showing JavaScript examples.

PubNub's SDK manages the subscribe loop and reconnection automatically. This page shows how to expose that behavior to your application so you can react to connection state changes.

Attach a status listener to your PubNub client so your application can tell a healthy idle connection from a lost one, and act when the SDK stops retrying. Attach it to the PubNub client object, not to an individual subscription or subscription set, and attach it once per client.

Before you start, make sure you have:

  • An initialized PubNub client with your keyset's keys and a userId. Refer to Quickstart.
  • At least one active subscription. The statuses on this page describe the subscribe connection, so a client that never subscribes emits none of them.

Nothing needs enabling in the Admin Portal, and status events need no add-on.

If a listener is already attached and you only need to know what to do with each status, skip to Branch on the status category.

Add the listener, then subscribe​

Add the listener to the client before you subscribe, because a listener receives only the events emitted after it's attached.

1

Most other SDKs document the same call in the Add connection status listener section of their Publish/Subscribe API reference, for example Python.

Keep the listener attached for the life of the client. Adding a second listener for the same purpose gives you duplicate status events to deduplicate.

Branch on the status category​

Status category names vary by SDK

The five categories below are conceptual. Every SDK exposes them differently: different constant names, different fields on the event object, and not every SDK emits all five. Check your SDK's status events reference before writing this code, for example JavaScript.

Compare the category on each event against your SDK's own constants, for example PNConnectedCategory in JavaScript.

StatusWhat to do
ConnectedClear any offline indicator in your UI. If the client had been disconnected before this event, run your catch-up path now.
Subscription changedUpdate whatever your application tracks about the current subscription from the channel and channel-group arrays on the event. Don't treat it as a reconnect.
DisconnectedTreat it as expected, because it follows your own request to stop. Resume the connection with your SDK's reconnect method rather than by calling subscribe again.
Disconnected unexpectedlyShow offline state and read the error field. The retries are already spent, so decide here whether to recover missed messages, and reconnect when it makes sense for the user.
Connection errorRead the error field before doing anything else. If it reports access denied, refresh the token. If it reports a network failure, reconnect when connectivity returns.

In a browser, the JavaScript SDK also emits two network-level categories ahead of these five: PNNetworkDownCategory and PNNetworkUpCategory. See Detect a browser network drop sooner.

Give Connection error and Disconnected unexpectedly separate handling even when they show the same offline UI, because repeating a request that was rejected reproduces the rejection. For why the two differ, refer to Two failures that mean different things.

Don't start your own retry loop while you wait for a status. The JavaScript SDK's current subscription workflow handles intermediate connecting and reconnecting states internally, emitting no status event until a retry sequence succeeds or gives up. Treat that silence as the SDK's own reconnection policy still working.

Resume the connection​

Call the reconnect method when the client sits in Disconnected after your own stop request, and after you replace a rejected token. Subscribing again doesn't restart the subscribe loop.

1

Reconnect in response to a user action or a status event rather than on a timer, because the SDK already applies its own reconnection policy to a failed request.

Refresh a token when a status reports access denied​

Follow this path only if your keyset uses Access Manager. A retry policy can't clear a rejected token, so this handling is yours.

  1. Read the error field on the Connection error event. In JavaScript, an access failure arrives as PNConnectionErrorCategory with PNAccessDeniedCategory nested in that field.
  2. Request a new token from your own server for the same userId, scoped with read permission on the channels and channel groups the client subscribes to.
  3. Set the new token on the client:
1

Then resume the connection, because setting the token doesn't restart the subscribe loop on its own.

The secret key grants privileged access to your PubNub application. It must remain on a trusted server and must never be included in client applications.

For the grant call itself, refer to How to update an expired token.

Detect a browser network drop sooner​

Apply this step only to the JavaScript SDK running in a browser. Other environments have no equivalent signal and reach a terminal status only after the retries are spent.

  • Leave listenToBrowserNetworkEvents at its default so the SDK also emits PNNetworkDownCategory and PNNetworkUpCategory. Use PNNetworkDownCategory to show offline state immediately instead of waiting for retries to finish.
  • Leave restore at its default so the SDK keeps the current timetoken and the channel and channel-group list across the drop.
  • If you set restore: false, track the subscribed channels and channel groups in your own cache and resubscribe when PNNetworkUpCategory arrives. The SDK resets both on network loss in that mode.

Confirm the current defaults for both options in the JavaScript configuration reference.

Verify the listener​

Test the failure paths before you rely on them.

  1. Subscribe to a channel and confirm you receive Connected.
  2. In your browser's developer tools, switch the network to Offline. In a browser, expect PNNetworkDownCategory right away. In other environments, wait for the retries to run out and expect Disconnected unexpectedly.
  3. Switch the network back on. Expect PNNetworkUpCategory in a browser, then Connected.
  4. To exercise the access-denied path, initialize a client with a token that has no read permission on the channel, then subscribe. Expect Connection error carrying an access-denied error.

Log the category and the error field in each case. A test that only checks that messages resume tells you nothing about which status your code took.

Was this page useful?

Last updated on