Ocamba Service Worker

Ocamba Service Worker

Learn how to integrate, configure, and migrate the Ocamba Service Worker for Web Push Notifications.

Overview

This guide covers how to configure the Ocamba Service Worker for Web Push Notifications.

If you are using our WordPress plugin, the Ocamba Service Worker file gets added automatically and you should not add these files to your site manually. Return to WordPress setup for more information.

What are service workers?

A Service Worker is a background script that runs in a separate thread from the main page. It enables features like push notifications, offline caching, and background sync. It’s installed when your site registers it and, although not always running, can be woken to handle events (including push) even after the user navigates away.

How to integrate Ocamba’s service worker

As you follow our Web SDK Setup guide, you will be provided the sw.js service worker file.

Download the service worker file

Download the sw.js file from the Ocamba dashboard or Download the Ocamba Service Worker File here.

The file contains a single line:

importScripts("https://cdn.ocmhood.com/sdk/osw-latest.js");

Upload the file to your server

Our SDK defaults to looking in your site’s root for the sw.js file, for example: https://yoursite.com/sw.js

You can simply upload this file to the root directory of your site and return to the Web push setup guide for next steps.

However, it is recommended to place this sw.js file in a subdirectory path that you will never link users to like https://yoursite.com/push/ocamba/sw.js.

You can place this file in the root, but it may conflict with other Service Workers you have now or may add in the future. Also, the file should be put in a permanent location path that will never change. Once a Service Worker is registered with the browser, it is difficult to change.

Service Worker requirements

The Ocamba service worker file sw.js must meet these requirements:

• The file must be publicly accessible, meaning you should be able to navigate to the file in a browser and see the code.
• The file must be served with a content-type of application/javascript; charset=utf-8.
• The file must point to the same site origin (your site domain). Pointing to a Service Worker on a different origin is not allowed. No CDNs or subdomains.

Confirm the service worker is setup correctly

Visit the service worker in your browser. You should see the code for the service worker:

importScripts("https://cdn.ocmhood.com/sdk/osw-latest.js");

If you uploaded the sw.js file to your site’s root (it is accessible at https://yoursite.com/sw.js) then no further action is needed.

However, if you put it in a subdirectory like https://yoursite.com/push/ocamba/sw.js then you will need to configure the path using one of the methods below.

Changing Service Worker Filename

What happens when you change the service worker filename?

If you need to change the service worker filename on your server (e.g., from A.sw.js to B.sw.js), existing subscribers will continue to receive push notifications without any disruption.

Example scenario:

• Week 1: Service worker file is named A.sw.js
• A user subscribes to push notifications
• Week 2: You upload a new file named B.sw.js and remove A.sw.js

What happens:

1. Existing subscribers continue receiving notifications - Their browser still has A.sw.js registered, and push notifications will continue to work
2. When users visit your site again - The browser will register the new B.sw.js file, and they remain subscribed
3. No subscription loss - Changing the filename does not affect existing subscribers or cause them to lose their subscription

Important: Update the service worker path in Ocamba

When you change the service worker filename on your server, you must update the service worker path in the Ocamba container settings to match the new filename.

Why this is critical:

• New users need the correct path to subscribe successfully
• New subscriptions will fail if the path in Ocamba doesn’t match the actual file location on your server
• Existing users are not affected and will continue working normally

How to update:

Update it in your Ocamba container settings in the dashboard.

Best practice: Keep the same filename

While changing the service worker filename doesn’t break existing subscriptions, it’s still recommended to keep the same filename across deployments for simplicity:

• Easier maintenance - No need to update configuration files
• Fewer moving parts - Less chance of misconfiguration
• Cleaner deployment - Just replace the file content, not the filename

Recommended approach:

# Always use the same filename
/sw.js  (update the content as needed)

Integrating Multiple Service Workers

If your website already uses its own service worker, you’ll need to integrate Ocamba’s service worker code with your existing implementation.

Option 1: Import Ocamba into your existing service worker

Add the following line at the beginning of your existing service worker file:

importScripts("https://cdn.ocmhood.com/sdk/osw-latest.js");

// Your existing service worker code below
// ... existing code ...

Option 2: Using Workbox

If you’re using Workbox for service worker generation, add the Ocamba import to your Workbox configuration:

// In your workbox-config.js or build configuration
{
  importScripts: [
    "https://cdn.ocmhood.com/sdk/osw-latest.js"
  ],
  // ... other Workbox options
}

FAQ

Why must I keep hosting the original ServiceWorker file URL if I change the name or location path?

This is required for those users who have not re-visited your site for the new filename to be picked up. The original ServiceWorker file will be fetched by the browser each time you send a push (if past cache expire time, max cache is 24 hours).

You will see a spike in 404 errors returned from your hosting provider when sending a push if the original ServiceWorker file isn’t available. This may result in more requests to your server. This also means those users won’t be getting the new Ocamba features and fixes.

Can I use a CDN for the service worker file?

No. The service worker file must be served from the same origin (domain) as your website. Browsers do not allow service workers to be loaded from a different origin, including CDNs or subdomains.

What happens if I delete the old service worker file too early?

Users who haven’t revisited your site since the migration will experience:

• Failed push notification delivery (404 errors)
• No ability to receive notifications until they revisit your site
• Potential loss of subscribers

It’s recommended to keep the old file available for at least 1 year.

How do I check if my service worker is registered correctly?

Open your browser’s Developer Tools:

1. Go to Application tab (Chrome) or Storage tab (Firefox)
2. Click on Service Workers in the left sidebar
3. You should see your service worker listed with the correct scope and status “activated”

You can also check programmatically:

Hood('pushstatus', (status) => {
  console.log('Push Status:', status)
  // status will be: 'granted', 'denied', or 'default'
})

Can I have multiple service workers on the same site?

Yes, but they must have different scopes. Each service worker controls only the pages within its scope. For example:

• Root service worker at /sw.js with scope /
• Ocamba service worker at /push/ocamba/sw.js with scope /push/ocamba/

However, only one service worker can control any given page.

Next steps

For more information, see:

• Web SDK Reference
• API Reference