# Watchlist Events

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

Watchlists are part of [user authentication](/docs/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.

```json
{
    "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

```js
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.

```json
{
    "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`.

## Related docs

- [User authentication](/docs/user-authentication)
- [User connections](/docs/user-connections)
- [WebSocket protocol](/docs/websocket-protocol)