Integrating the SDK into your website is pretty easy.
Here is an example of what the minimal configuration looks like:
If you're running the SDK in HTTP/Multidomain mode, you can skip straight to Icons.
By downloading and extracting the SDK's package, you should end up with a file named
You will need to upload this file to your website's root, and not in a subfolder. It should be publically accessible.
For example, for a website that you'd access at
https://batch.com, this is OK:
And those are not:
https://batch.com/static/batchsdk-worker-loader.js https://batch.com/js/batchsdk-worker-loader.js https://dashboard.batch.com/batchsdk-worker-loader.js https://batch-static.com/batchsdk-worker-loader.js
You can set two default icons for your notifications visuals:
- A default icon, displayed on notifications sent to desktop and Android devices.
- A small icon, displayed on Android devices only.
We strongly recommend you add them since they help your users identify your website. These files can be at any URL, not only on the same domain as your page or even on its root.
Should be a square image (JPG or PNG), with an recommended size of 192x192 pixels. You can go as low as 80x80, but making it too big or too small will result in a pixellated display. It can contain color and be of any shape you want. If you don't specify it, Chrome users will see a white square instead of what could have been your logo.
It has a recommended size of 96x96 pixels, and will act as a mask, meaning that it will only use the alpha channel of your image and will color the resulting shape. If you don't specify it, users will see the Chrome logo. You can easily create one using the Android Assets Studio. As of writing, Firefox does not support this feature.
Make sure the server where your icons are stored can handle traffic. Every user getting a notification for the first time will trigger a download. Do not hesitate to offload this work to a specialized static host like a CDN (e.g. Cloudfront, etc...).
The following points are more general SDK Configuration informations. While we recommend that you read them, you can skip that part and go straight to the end of the page to finalize your integration.
As you have probably noticed, there is a
dev: true configuration parameter that has been added by the dashboard on your behalf.
It is essential that you remove this parameter in production, as it can prevent the SDK from working.
If you serve different parts of your website on multiple subdomains or serve mixed content, you might want to force the sdk to run in HTTP/Multidomain mode.
For that, you will need to add
sameOrigin: false in the setup object.
While developing your website locally, or deploying it to a staging environment, you might find that the SDK doesn't work in fully secure mode.
This is because you might not have been through the hassle of securing your local dev environment on your staging.
You've got two ways to fix this:
- If your local dev environment uses a "fake" domain (such as "mywebsite.local"), you'll have to issue a self signed certificate
- Fall back on the HTTP mode during development/staging.
We do not recommend this, as unexpected issues can arise.
If you develop your website on your computer but access it though
http://localhost, most browsers will treat it as fully secure, as this is URL is considered secure for convinience. You should test in an environment closer to your production one before releasing your update.
As you may know, only one Service Worker per domain can be registered. Progressive Web Apps (PWA) come with one, for example. By default, Batch will try to register its own Service Worker (named
batchsdk-worker-loader.js) as soon as possible which makes harder to add your own code in there.
You can prevent Batch from registering its own Service Worker by adding
useExistingServiceWorker: true in the setup object.
It means that you'll have to register a Service Worker yourself, early on page load.
You will also have to load Batch into your existing Service Worker. Once you've downloaded
batchsdk-shared-worker.js, you've got two options:
batchsdk-shared-worker.jsat your website's root, and import it using
- Copy paste the code from that file into your Service Worker source
Batch will wait up to 5 seconds for your Service Worker to be ready. If needed, you can extend the duration by adding
serviceWorkerTimeout: 10 (where 10 would be in seconds) in the setup object.
Note: Do NOT import or copy
batchsdk-worker-loader.js, as this version is designed for exclusive, Batch-controlled Service Worker usage. Please make sure you import or copy
Now that the base SDK has been integrated, we'll show you the best way to ask your users to enable notifications on your website: