Introducing Watchlist: notify users when their friends are online

“Are any of the people I follow online right now?”

This is one of the questions end users often ask when using a community-focused app.

With today’s release on Pusher Channels, you can easily enable your end users to create a watchlist and observe the connection status of the people they follow. It can be a followers or friends list, depending on the realtime app you’re building.

Online and offline status notifications help to keep connected groups of users in touch. There are countless scenarios that rely on knowing when people of interest are online: friends on a social media platform for example; colleagues in a collaboration tool; and team members in multiplayer games all need to understand the availability of their followers.

With Watchlists, you’ll be able to build user-specific online status notifications more easily.

Watchlist Online Status

Pusher Presence channels already offer the functionality to send users notifications when others join or leave the same channel, but this mechanism is not a perfect solution for all presence use cases.

Presence Channels are a great solution to keep track of who is subscribed to a channel and notify channel members when someone joins or leaves. However, in many cases end users are more interested in whether people they know or follow are online than just seeing the movement of random subscribers. For everything you need to know about Presence channels, check out Pusher Presence Channels: when and how to use them.

Rather than requiring you to apply presence on a per channel basis, the concept of Watchlist enables you to build presence functionality at the app level via Online Status notifications. By implementing the Online Status feature, users will not receive updates about all the people in the channel (which can get spammy), they can get notified about users relevant to them, users they “watch”.

Your application server keeps track of user relationships and you can implement follow or request friendship actions as needed for your application. Depending on the use case and type of app, note that the term followers could vary. For example, in your realtime app, you may call them contacts or friends.

Using Watchlist Online Status

The Online Status feature for Watchlists builds on User Authentication, a mechanism we released earlier in the year.

When the client side calls Pusher.signin(), the authentication request goes to the application server checking the user’s identity. Then the application server responds with the user ID and the Watchlist for that user.

A Watchlist is an array of user IDs. These user IDs represent the circle of interest of a particular user. For example, friends or followers.

Every time a connection is established on the client side of the application and the user signs in, a request is made to the application server via which an updated version of the watchlist can be provided. The provided Watchlist will remain in effect until this connection is ended.

This Watchlist is then transferred to Pusher and used as a mechanism to notify the user about the online status of users in their watchlist.

For optimal use of this feature, a watchlist should be short. Otherwise, the user may be bombarded with events about many users going online and offline. In that case, the user will struggle to consume the huge amount of events and the feature will lose its effectiveness.

For this reason, we’ve defaulted the maximum number of IDs each user can have in their Watchlist. If you’d like to increase this, reach out to our support team.

Here’s a two-step summary of the Watchlist Online Status:

• The server side provides a Watchlist for the end user. This happens during user authentication.

php
1app.post("/pusher/user-auth", (req, res) => {  
2  const socketId = req.body.socket\_id;
3
4  // Replace this with code to retrieve the actual user id and watchlist  
5  const user = {  
6    id: "some\_id",  
7    watchlist: \['another\_id\_1', 'another\_id\_2'\]  
8  };
9  const authResponse = pusher.authenticateUser(socketId, user);  
10  res.send(authResponse);  
11});
Copy

• The client side subscribes to Watchlist events.

javascript
1pusher.signin();
2
3const watchlistEventHandler = (event) => {  
4// event.user\_ids  
5// event.name  
6};  
7pusher.user.watchlist.bind('online', watchlistEventHandler);  
8pusher.user.watchlist.bind('offline', watchlistEventHandler);\`
Copy

Here’s a sequence diagram to illustrate this.

Make sure users need to give permission before other users can add them to the Watchlist. For example, a friend list or a list of followers.

You can use Watchlist Online Status for various follow/watch scenarios in your app. Check out the Watchlist Online Status documentation to start building.

In the meantime, reach out to us if you need any help with this feature.