Web Push is in the closed pilot phase. If it is of interest to join the pilot when further customers are added, please register your interest with your Emarsys Client Success Manager. The details below are for the current capabilities of the feature, however, we plan to release updates before it enters a general release stage.
This article provides developers information for configuring websites to receive web push notifications sent from the Emarsys platform.
Contents
Supported Browsers
Confirmed below are the list of browsers the Emarsys web SDK supports web push notifications
- Chrome
- Firefox
- Opera
- Edge
Safari support will be released in Q4 2020.
It is not possible to use Web push notifications in both incognito or guest mode.
Resources
The Emarsys Web Push SDK and Service Worker files will be provided to pilot customers by the Emarsys Product team.
SDK and Service Worker
Add the SDK file emarsys-me-web-push-sdk.js and service worker file emarsys-me-service-worker.js to the root directory of the website.
Initialise the SDK by loading the SDK file asynchronously.
<script type="text/javascript" src="/emarsys-me-web-push-sdk.js" async></script>Queue the initialisation until the SDK file is fully loaded:
<script type="text/javascript">
var MeWebPushSdk = MeWebPushSdk || []
MeWebPushSdk.push(['init', {
applicationCode: 'XXXXX-XXXXX', // your application code
defaultNotificationTitle: 'Your Default Title', // sets your default title for push notifications
defaultNotificationIcon: 'https://yoursite.com/img/your-logo.png', // URL to your notification icon
autoSubscribe: false, // If true, prompts a user to subscribe for pushes upon SDK initialization which is not recommended
serviceWorker: {
url: 'emarsys-me-service-worker.js',
applicationServerPublicKey: 'your-public-vapid-key'
}
}])
</script>API
The public functions detailed below should only be used after the SDK has completed initialisation.
Subscribe
Use the subscribe method to request to send push notifications to the contact. If the contact has already subscribed, the method will just return.
function subscribe (): Promise<void>;When a contact grants permission to receive push notifications, the callback onSubscribe will be invoked.
Unsubscribe
Use the unsubscribe method to disable push notifications for a contact.
function unsubscribe (): Promise<void>;isSubscribed
Returns a boolean indication if the web browser and user is fully registered. This is the case if:
- The user granted the allowance for receiving push notifications (has a push token),
- The browser is registered in our backend and
- The user is logged in.
function isSubscribed (): Promise<boolean>;Contact Link
Links a specific contact using a given contact field ID and contact field value to the browser.
The contact fieldId and fieldValue are optional. If the fields are omitted, the browser will be linked to an anonymous contact record.
function login (contactInfo?: ContactInfo): Promise<boolean>;
type ContactInfo = {
fieldId: number,
fieldValue: string
}Contact Unlink
Unlinks the browser from the known contact record. The anonymous contact record will continue to be linked to the browser.
function logout (): Promise<boolean>;getLoggedInContact
Returns the information about the contact which is currently linked to the browser.
function getLoggedInContact (): Promise<ContactInfo | {} | undefined>;Returns one of the following
- The ContactInfo consisting of the fieldId and fieldValue if the contact record linked to the browser is that of a known contact.
- An empty object {} if the contact record linked to the browser is anonymous.
- Undefined if there is neither a known nor the anonymous contact linked to the browser.
Event Listeners
To register a callback function you have to use the public push method of the SDK and you should register all of your callbacks in a<script>part which is placed at the end of your HTML.
type HandlerFn = (params?: any) => any
type SdkOnReadyCallback = HandlerFn
type SdkInitCallback = ['init', IInitParams]
type MeWebSdkEvent = 'onReady' | 'onSubscribe' | 'onUnsubscribe' | 'onSWInitError' | 'onPermissionPrompt' | 'onPermissionDenied' | 'onPermissionGranted'
type MeWebSdkEventCallback = [MeWebSdkEvent, HandlerFn]
type SdkCommand = SdkInitCallback | SdkOnReadyCallback | MeWebSdkEventCallback
function push (sdkCommand: SdkCommand): void;init
Is invoked after the web page and SDK code are fully loaded. The init callback is part of the SDK. The initialisation parameters are required to be passed to the push method.
type SdkInitCallback = ['init', IInitParams]
type SdkCommand = SdkInitCallback | ...
function push (sdkCommand: SdkCommand): void;onReady
The onReady callback is invoked after the SDK has been initialised. It is possible to register the desired callback by passing a function to the push method or use the same approach which can be used for all other supported events.
<script>
MeWebPushSdk.push(function() {
console.log('EVENT: onReady');
// do whatever you need to do after the SDK is ready
});
// further event handler registrations...
</script>Further Events
All callbacks for events listed in this section have to be registered by passing an array object to the push method, which consists of the event name and the callback function.:
-
onSubscribe: Invoked when the browser is registered with our backend and we have a push token and a user is linked to the browser. -
onUnsubscribe: Invoked after the successful execution of unsubscribe. -
onSWInitError: Invoked in case there was an error detected during the registration of the service worker (SW). -
onPermissionPrompt: Invoked when it is necessary to prompt the user for allowance of push notifications. -
onPermissionDenied: Invoked when the user generally denied reception of push notifications. -
onPermissionGranted: Invoked when the user granted the reception of push notifications.
<script>
// ...
MeWebPushSdk.push(['onPermissionPrompt', function() {
console.log('EVENT: onPermissionPrompt');
}]);
</script>