Skip to main content

Browser SDK Quickstart

Add web push notifications to your web application in under 5 minutes.

Prerequisites​

Installation​

Option 1 — npm​

Install the package from npm:

npm install @hoberhq/browser-sdk

Then import it in your application entry point:

import Hober from '@hoberhq/browser-sdk';

Option 2 — CDN (Script Tag)​

Add the following script tag to your HTML <head> or just before </body>:

<script src="https://cdn.hober.io/browser-sdk@1.0.0/index.js"></script>

The Hober object is exposed as a global variable after the script loads.

Service Worker Setup​

The Browser SDK relies on a service worker to receive push notifications in the background.

Step 1 — Copy hober-sw.js to your web root​

Download or copy the hober-sw.js file and place it at the root of your public web server so that it is served at /hober-sw.js.

npm users — the file ships inside the package:

cp node_modules/@hoberhq/browser-sdk/dist/sw/hober-sw.js public/hober-sw.js

CDN users — save the file from:

https://cdn.hober.io/browser-sdk@1.0.0/hober-sw.js

Place it in your static/public directory so that it is reachable at https://yourdomain.com/hober-sw.js.

important

The service worker must be served from the root path (/hober-sw.js). If it is placed in a subdirectory its scope will be limited and push notifications will not work.

Step 2 — Verify the file is accessible​

Navigate to https://yourdomain.com/hober-sw.js in a browser. You should see the service worker JavaScript source. A 404 response means the file is not in the right location.

Initialization​

Call Hober.init() once, as early as possible in your application lifecycle (e.g. in your app entry point or DOMContentLoaded handler):

Hober.init({
  sdkKey: 'YOUR_SDK_KEY',
});

Hober.init() must be called before any other SDK method. You can find your sdkKey in the Hober dashboard under Settings > SDK Keys.

Request Notification Permission​

Prompt the user for notification permission. This must be triggered by a user gesture (button click, etc.) to satisfy browser security requirements:

const granted = await Hober.requestPermission();

if (granted) {
  console.log('Notification permission granted.');
} else {
  console.warn('Notification permission denied.');
}

Hober.requestPermission() returns a Promise<boolean> — true when the user grants permission, false when they deny or dismiss.

Identify a Subscriber​

Associate the current user with a Hober subscriber record. Call this after the user logs in:

await Hober.identifySubscriber({
  externalId: 'user-123',
  email: 'user@example.com',
});
ParameterTypeRequiredDescription
externalIdstringYesYour internal user ID
emailstringNoUser email for segmentation

Register the Device​

Subscribe the current browser to push notifications. Call this after permission has been granted:

await Hober.registerDevice();

This registers the browser with the Web Push Protocol and stores the subscription endpoint in Hober. After this call, the device will start receiving push notifications sent via the Hober API or dashboard.

Complete Example​

<!DOCTYPE html>
<html lang="en">
<head>
  <meta charset="UTF-8" />
  <title>My App</title>
  <script src="https://cdn.hober.io/browser-sdk@1.0.0/index.js"></script>
</head>
<body>
  <button id="enable-notifications">Enable Notifications</button>

  <script>
    Hober.init({ sdkKey: 'YOUR_SDK_KEY' });

    document.getElementById('enable-notifications').addEventListener('click', async () => {
      const granted = await Hober.requestPermission();
      if (!granted) return;

      await Hober.identifySubscriber({ externalId: 'user-123', email: 'user@example.com' });
      await Hober.registerDevice();

      console.log('Push notifications enabled!');
    });
  </script>
</body>
</html>

Browser Compatibility​

The Web Push API is supported in all major modern browsers. The table below reflects support as of 2024:

BrowserMinimum VersionNotes
Chrome50+Full support
Firefox44+Full support
Safari16+Requires macOS Ventura or iOS 16.4+
Edge17+Full support (Chromium-based Edge recommended)
note

Safari on iOS requires iOS 16.4+ and the site must be added to the Home Screen to receive push notifications via the Web Push standard.

Troubleshooting​

Permission Denied​

Symptom: Hober.requestPermission() returns false and the browser shows no permission prompt.

Cause: The user has previously denied notification permission for your domain.

Fix: Users must manually reset the permission in their browser settings:

  • Chrome: Settings > Privacy and security > Site settings > Notifications
  • Firefox: Preferences > Privacy & Security > Permissions > Notifications
  • Safari: Safari > Settings for This Website > Notifications
  • Edge: Settings > Cookies and site permissions > Notifications

You cannot re-prompt a user who has denied permission. Show a help message directing them to browser settings.

Service Worker Not Found​

Symptom: Hober.registerDevice() throws an error mentioning the service worker, or you see a 404 for /hober-sw.js in the browser DevTools Network panel.

Cause: The hober-sw.js file is missing from your web root or is being served from the wrong path.

Fix:

  1. Confirm hober-sw.js is placed in your public/ (or equivalent static) directory.
  2. Visit https://yourdomain.com/hober-sw.js directly — you should see JavaScript source, not a 404.
  3. If you are using a build tool (Webpack, Vite), ensure static files in public/ are copied to the output directory.

HTTPS Requirement​

Symptom: The SDK or browser throws an error about a secure context, or navigator.serviceWorker is undefined.

Cause: Web Push and service workers require a secure context — the page must be served over HTTPS. The only exception is localhost, which browsers treat as secure for local development.

Fix:

  • Ensure your production site is served over https://.
  • For local development, use http://localhost (not http://127.0.0.1 or a custom hostname without HTTPS).
  • Do not test on http:// staging environments — use a self-signed certificate or a tunnel (e.g. ngrok) if needed.

Next Steps​