Pushpad

Targeting specific users with web push notifications

Pushpad makes it easy to target specific users (or groups of users) with web push notifications.

When a user subscribes to your web push notifications you can attach a user ID to that subscription. Then you can send web push notifications to the user browser using the user ID. This is especially useful for websites and web apps where users can sign up / log in and when you need to send transactional notifications with the API.

You can update the user ID (uid) associated to a browser at any time using the Javascript SDK:

// call this method when the user is logged in on your website, in order to keep track of the user ID
pushpad('uid', 'myUser123', 'mySignature');

mySignature is the HMAC-SHA256 signature of the user ID. The signature is hex-encoded. The key used to generate the signature is an access token. If you don't want to provide a signature read this section.

The signature is required as a form of authentication: without a signature a malicious user could pretend to be another user and receive all his notifications.

Warning: if you use a token with full access to generate the signature, that signature is valid for any project of your account. A user may use the signature to subscribe with the same uid to any of your projects. For this reason you should always use tokens with restricted access to generate the signatures.

Warning: the signature is only checked before setting the user ID associated to the subscription. However the user ID can be removed and tags can be altered even without the signature.

You can use the server-side libraries to easily generate the signature. Then you can pass the current user ID and the signature from your backend to the frontend. For example:

// write data from server directly into a JavaScript variable (or data attribute)
var userId = '<?= $current_user_id ?>';
var userIdSignature = '<?= Pushpad::signature_for($current_user_id) ?>';
pushpad('uid', userId, userIdSignature);

// or alternatively you can fetch the data from server
fetch('https://example.com/user')
  .then(response => response.json())
  .then(data => pushpad('uid', data.userId, data.userIdSignature));

A subscription to web push notifications can have at most one user ID at a time associated to it. Any new user ID will replace the previous one. This makes sense because even if a browser is shared among multiple users, you have only one user at a time logged in on your website with that browser.

You can also remove the user ID from the subscription when the user logs out.

Once you have associated the user IDs to the subscriptions, it is simple to target specific users or group of users. Basically when you send the notifications you can list the user IDs that must receive the notification: the notification will be delivered to all the browsers that belong to that users. For example:

$notification = new Pushpad\Notification(array('body' => "Hello, world!"));

# deliver to a user
$notification->deliver_to("myUser123");

# deliver to a group of users (you can include thousands of users in a single API call)
$notification->deliver_to(["myUser123", "AnotherUser"]);

If a user is not subscribed to your web push notifications, that user ID will be simply ignored. If a user is subscribed with multiple browsers, the notification will be sent immediately to all browsers.

The advantage of this method is that you will never have the problem of keeping the data synchronized between your server and Pushpad, since the only piece of information is the uid which never changes (use the primary key of the user in your database for example). This method is also efficient since you can reach thousands of users with just one API call.

Setting the user ID without a signature

The signature is enabled by default in project settings and it is required for security reasons: without a signature a user is free to set arbitrary user IDs and receive the notifications directed to other users.

However, if you don't want to compute the signature on your server, there is an alternative.

Go to your project settings and change the User ID signature field from HMAC-SHA256 to None.

Then you can assign a user to the push subscription of the current browser with this simple code:

pushpad('uid', 'myUser123');
// or
pushpad('subscribe', function () {}, { uid: 'myUser123' });

Warning: if you disable the signature verification, you should use long, random tokens for the uid, and not predictable IDs, otherwise a malicious user can try to subscribe to the notifications of another user.

If you disable the signature verification and you want to increase the security of notifications, you should use random tokens to identify your users. For example:

Usually, if you decide to disable the signature verification, we recommend to add a column with a random token to your users table in your database. Then pass that value to Pushpad (as the uid), instead of the actual user ID. You will also need to use that value to send notifications to that user later. Finally you can also "log out" a user from notifications by changing that value in your database.

Disabling the signature verification is also useful if you only send general marketing notifications (not personal or sensitive notifications) and you don't want to deal with the additional complexity of a signature.

Is a user subscribed to push notifications?

Sometimes you might want to know whether a user is subscribed to your web push notifications: