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');
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:
When a user is surfing your website you can use the
statuscallback is useless, and you must detect this second case with the
When you send a push notification with the libraries or the REST API, you can read the returned
uidsarray to determine which of the users you specified as recipients are subscribed to your notifications. For example if you set
["user1", "user2"]as the recipients, but only the first is subscribed, then you get
["user1"]in response and the delivery to
"user2"is simply ignored. This means that you can just trigger the notifications without worrying about the fact that the users are subscribed or not. The user IDs in the response are only available if you specify some
uidsin the request: this feature is not available for broadcast notifications. Note that even if a user has a subscription, many things can go wrong and you cannot be sure that he will see the notification (e.g. the user may be subscribed with a browser that he doesn't use anymore).
- You can retrieve the subscriptions for a given user ID from the dashboard or with the REST API.