Upgrade @magicbell/webpush to v2

Introduction

MagicBell is tweaking the vocabulary, and turning different integrations into one coherent experience, regardless of what the underlying provider is. As part of that work, we've published a v2 version of our @magicbell/webpush package, greatly simplifying all user scoped operations around the webpush channel.

The changes are breaking, but given that the API surface of v1 is small, the migration shouldn't take too much of your time.

Let's get started.

The WebPushClient

In v1, all operations were functional, there wasn't something like a client instance, instead credentials were passed to every function you'd invoke. We now expose a client which enables you to provide credentials once, and then simply call the methods you need.

ts
import { WebPushClient } from '@magicbell/webpush';

const client = new WebPushClient({
  apiKey: '024…0bd',
  userEmail: 'person@example.com',
  userHmac: 'NCI…I6M',
});

await client.isSubscribed();
await client.subscribe();
await client.unsubscribe();

Subscribe to push notifications

Subscribing to push notifications used to be a two-step flow; get the authentication tokens, and then subscribe to push notifications. In v2, it's a matter of calling client.subscribe() on the client instance.

diff
- import { getAuthToken, subscribe } from '@magicbell/webpush';
+ import { WebPushClient } from '@magicbell/webpush';

- const token = await getAuthToken({
+ const client = new WebPushClient({
  apiKey: '024…0bd',
  userEmail: 'person@example.com',
  userHmac: 'NCI…I6M',
});

- await subscribe({
-   token: token.token,
-   project: token.project,
- });
+ await client.subscribe();

Unsubscribe from push notifications

This is a new method that didn't exist in previous versions. Unsubscribing is now as simple as calling client.unsubscribe() on the client instance, giving your users the option to "pause" the push notifications.

ts
import { WebPushClient } from '@magicbell/webpush';

const client = new WebPushClient({
  apiKey: '024…0bd',
  userEmail: 'person@example.com',
  userHmac: 'NCI…I6M',
});

await client.unsubscribe();

Get subscription status

Verifying or getting the user's subscription status used to be a two-step flow; get the authentication tokens, and then subscribe to push notifications. In v2, it's a matter of calling client.isSubscribed() on the client instance.

diff
- import { getAuthToken, isSubscribed } from '@magicbell/webpush';
+ import { WebPushClient } from '@magicbell/webpush';

- const token = await getAuthToken({
+ const client = new WebPushClient({
  apiKey: '024…0bd',
  userEmail: 'person@example.com',
  userHmac: 'NCI…I6M',
});

- const subscribed = await isSubscribed({
-   token: token.token,
-   project: token.project,
- });
+ const subscribed = await client.isSubscribed();

Get authentication token

The authentication token is no longer required for basic functionality, but can still be used to for example transfer the session to a popup (which is good practice, as you shouldn't transfer the user credentials via an url.)

diff
- import { getAuthToken } from '@magicbell/webpush';
+ import { WebPushClient } from '@magicbell/webpush';

- const token = await getAuthToken({
+ const client = new WebPushClient({
  apiKey: '024…0bd',
  userEmail: 'person@example.com',
  userHmac: 'NCI…I6M',
});

+ const token = await client.getAuthToken();

API calls

The methods mentioned above are the ones you use when interacting with the browser directly. They depend on a service worker, and use that to create or delete push subscriptions using the browser's push manager.

The library now also exposes functions to interact with the MagicBell API directly, leaving all browser interaction for you to implement. Think of use cases where you already have a service worker, and just want to push the channel tokens to our backend, or because you need to list all the currently active channel tokens so the user can unsubscribe from a device they no longer control.

Please read more about those methods in the docs for @magicbell/webpush.