Watchlist Events

Watchlist events tell a signed-in user when selected other users come online or go offline.

Watchlists are part of user authentication. A user is online when at least one active connection has completed pusher:signin for that user_id.

#Provide a watchlist

Include watchlist in the signed user_data returned by your user auth endpoint.

{
    "id": "user-123",
    "name": "Ada",
    "watchlist": ["user-456", "user-789"]
}

The exact JSON string must be signed as part of user authentication.

#Sign in and bind

pusher.signin();

pusher.user.watchlist.bind('online', (event) => {
    for (const userId of event.user_ids) {
        console.log(`${userId} online`);
    }
});

pusher.user.watchlist.bind('offline', (event) => {
    for (const userId of event.user_ids) {
        console.log(`${userId} offline`);
    }
});

#Event shape

SDKs expose the events as online and offline. The underlying payload contains user ids.

{
    "name": "online",
    "user_ids": ["user-456"]
}

#Behavior

  • A watched user is online when one or more of their connections are signed in.
  • They become offline after their final signed-in connection closes.
  • Multiple tabs for the same user_id still produce one online state.
  • Presence-only users do not count unless they also completed pusher:signin.

Prefer raw markdown? View this page as markdown.