Pushpad Logo 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 subscription at any time:

// 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');
https://SUBDOMAIN.pushpad.xyz/p/PROJECT_ID?uid=myUser123&uid_signature=mySignature

mySignature is the HMAC-SHA1 signature of the user ID. The signature is hex-encoded. The key used to generate the signature is an access token.

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 libraries to easily generate the signature. For example:

pushpad('uid', 'myUser123', '<?= Pushpad::signature_for("myUser123"); ?>');

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.

Is a user subscribed to push notifications?

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