Usage with npm

Here’s how to install and use the Pushwoosh Web Push Notifications SDK in your project using npm. This guide assumes you have a basic understanding of npm and JavaScript module imports.

npm install web-push-notifications

When using the SDK via npm, the service worker file is located at:

node_modules/web-push-notifications/service-worker.js

Important: During your build or deployment process, you must copy this service worker file to the root of your website. This is crucial for push notifications to work correctly.

For example, in a webpack project, you can use copy-webpack-plugin:

const CopyWebpackPlugin = require('copy-webpack-plugin');

module.exports = {
  // ...other webpack config
  plugins: [
    new CopyWebpackPlugin({
      patterns: [
        {
          from: 'node_modules/web-push-notifications/service-worker.js',
          to: 'service-worker.js' // Copies to output directory root
        }
      ]
    })
  ]
};

If you’re using Vite, you can use the vite-plugin-static-copy plugin:

import { defineConfig } from 'vite';
import { viteStaticCopy } from 'vite-plugin-static-copy'

export default defineConfig({
  // ...other vite config
  plugins: [
    // ...other plugins
    viteStaticCopy({
      targets: [
        {
          src: 'node_modules/web-push-notifications/service-worker.js',
          dest: '' // Copies to build output root
        }
      ]
    })
  ]
});

For other build systems, use their respective file copying mechanisms to ensure the service worker is available at your website’s root.

The Pushwoosh Web SDK comes with four built-in UI widgets to enhance user interaction and streamline the subscription process. While the PWSubscriptionPromptWidget is primarily configured through the Pushwoosh Control Panel and browser settings, the other three widgets (PWSubscriptionButtonWidget, PWSubscribePopupWidget, and PWInboxWidget) offer detailed configuration options directly within the init method of the SDK.

Here’s an overview of each widget:

1. Subscription Prompt (PWSubscriptionPromptWidget) This widget is responsible for displaying the browser’s native prompt to ask users for permission to send push notifications. Its behavior is largely governed by browser standards and settings configured in your Pushwoosh Control Panel. It does not have specific configuration parameters within the pushwoosh.push(['init', {...}]) call.

2. Subscription Button (PWSubscriptionButtonWidget) This widget adds a floating button (often a bell icon) to your site, allowing users to easily subscribe to or manage their notification preferences.

• Configuration: Settings for this widget are managed under the subscribeWidget object in the init call.
• Learn more: Push Subscription Button

3. Custom Subscription Popup (PWSubscribePopupWidget) A customizable pop-up that provides a more engaging way to ask for notification permissions before showing the native browser prompt.

• Configuration: Customize its appearance and behavior using the subscribePopup object in the init call.
• Learn more: Custom Subscription Popup

4. Inbox Widget (PWInboxWidget) This widget integrates an in-app message center, allowing users to view a history of rich push notifications.

• Configuration: Managed via the inboxWidget object in the init call.
• Learn more: Web Inbox Widget

You can then initialize and run these widgets as shown in the examples below:

import { Pushwoosh } from 'web-push-notifications';
import { PWSubscriptionPromptWidget } from 'web-push-notifications/widget-subscription-prompt';
import { PWSubscriptionButtonWidget } from 'web-push-notifications/widget-subscription-button';
import { PWSubscribePopupWidget } from 'web-push-notifications/widget-subscribe-popup';
import { PWInboxWidget } from 'web-push-notifications/widget-inbox';

const pushwoosh = new Pushwoosh();

pushwoosh.push(['init', {
  applicationCode: 'XXXXX-XXXXX', // your Pushwoosh Application Code
  apiToken: 'XXXXXXX', // Device API Token
  defaultNotificationTitle: 'Pushwoosh',
  defaultNotificationImage: 'https://yoursite.com/img/logo-medium.png',
  serviceWorkerUrl: '/service-worker.js', // path to your copied service worker

  // Custom Subscription Popup settings
  subscribePopup: {
    enable: true // Enable the subscription popup
    // other options can be added here
  },

  // Push subscription button settings
  subscribeWidget: {
    enable: true // Enable the subscription button widget
    // other options can be added here
  },

  // Inbox widget settings
  inboxWidget: {
    enable: true // Enable the inbox widget
    // other options can be added here
  }
}]);

pushwoosh.push(async () => {
  try {
    const widget = new PWSubscriptionPromptWidget(pushwoosh);
    await widget.run();
  } catch (error) {
    console.error('PWSubscriptionPromptWidget initialization failed:', error);
  }
});

pushwoosh.push(async () => {
  try {
    const widget = new PWSubscriptionButtonWidget(pushwoosh);
    await widget.run();
  } catch (error) {
    console.error('PWSubscriptionButtonWidget initialization failed:', error);
  }
});

pushwoosh.push(async () => {
  try {
    const widget = new PWSubscribePopupWidget(pushwoosh);
    await widget.run();
  } catch (error) {
    console.error('PWSubscribePopupWidget initialization failed:', error);
  }
});

pushwoosh.push(async () => {
  try {
    const widget = new PWInboxWidget(pushwoosh);
    await widget.run();
  } catch (error) {
    console.error('PWInboxWidget initialization failed:', error);
  }
});

See an example application with React and Vite: https://github.com/Pushwoosh/websdk-npm-vite-react-example