This package provides a convenient interface to subscribe to browser/web push notifications using MagicBell.
Installation
Install the package with npm:
shellnpm install @magicbell/webpush --save
or yarn:
shellyarn add @magicbell/webpush
Usage
Note that some of our endpoints used for push subscriptions, require a JWT for authentication. This is because we often want to show the "enable push subscriptions" button in a dialog (window.open
), but we don't want to expose the userMac
to the client via browser history. Therefore, we need to authenticate the request with a JWT token, which expires and thereby is relatively safe to expose to the client via the address bar.
Use the getAuthToken
request to exchange the API Key based credentials for a JWT based token. Then use the subscribe
request to subscribe the user to push notifications.
Get a JWT token
To get a JWT token, you need to authenticate against the MagicBell API. You can do this by using your API key and user credentials. You only need to provide either userEmail
or userExternalId
and optionally - but recommended - userHmac
. The latter is used for HMAC authentication.
jsimport { getAuthToken } from '@magicbell/webpush';
// authenticate user by external id
getAuthToken({
apiKey: '024…0bd',
userExternalId: 'user_123',
userHmac: 'NCI…I6M',
});
// or based by their email address
getAuthToken({
apiKey: '024…0bd',
userEmail: 'person@example.com',
userHmac: 'NCI…I6M',
});
Options
apiKey String
Your MagicBell API key. You can find it in the MagicBell dashboard.
userEmail String
The email address of the user you want to authenticate. Required if no userExternalId
is provided.
userExternalId String
The external ID of the user you want to authenticate. Required if no userEmail
is provided.
userHmac String
The HMAC signature of the user you want to authenticate. Required if you want to use HMAC authentication.
Subscribe
Subscribe the user to push notifications. This method will register a service worker if it isn't already registered. The service worker will be registered at the path provided in the serviceWorkerPath
option. If the service worker is already registered, it will be used to subscribe the user.
jsimport { subscribe } from '@magicbell/webpush';
subscribe({
token: 'jwt-token',
project: 'string',
serviceWorkerPath: '/sw.js',
});
Options
token String
The JWT token you received from the MagicBell API. This token is used to authenticate the request.
project String
The random subdomain that MagicBell generated for your service worker registration.
serviceWorkerPath String
The path to the service worker file. Defaults to /sw.js
.
Register a service worker
A helper that can be used to register a service worker, prior to calling subscribe
. This preflight allows for a faster
subscription process. If this method isn't used, registration will be done during subscribe
.
Registration will be skipped if a service worker is already registered. In which case, the active registration will be returned.
The returned promise resolves when the registration is ready.
jsimport { registerServiceWorker } from '@magicbell/webpush';
registerServiceWorker({
path: '/sw.js',
});
Options
path String
The path to the service worker file. Defaults to /sw.js
.
Prefetch config
To speedup the subscription process, you can prefetch the config. This will separate the subscription from config fetching, and thereby reduce the time to subscribe. The method requires the same options as subscribe
.
jsimport { prefetchConfig } from '@magicbell/webpush';
prefetchConfig({
token: 'jwt-token',
project: 'string',
serviceWorkerPath: '/sw.js',
});
isSubscribed
Check if the user is subscribed to push notifications in the current browser.
jsimport { isSubscribed } from '@magicbell/webpush';
const subscribed = await isSubscribed({
token: 'jwt-token',
project: 'string',
});
if (subscribed) {
// Do something
} else {
// Do something else
}