Web > SDK Integration

Initial setup

Integrating the SDK into your website is pretty easy.

Add the JavaScript snippet to your page

The JavaScript you need to add has been given to you when you created your app on the dashboard. If you missed it, go on the dashboard, open your website's settings, and press "Get the code" in the "Push settings" tab. You'll find a snipped pre-filled with a minimal configuration to get you up and running.

To ensure delivery, this JavaScript snippet should at least be added in a page that the users are likely to visit. It will also need to be added in every page in which you wish to call the SDK's API.

Here is an example of what the minimal configuration looks like:

<script type="text/javascript">
(function(b,a,t,c,h,e,r){h='batchSDK';b[h]=b[h]||function() {
(b[h].q=b[h].q||[]).push(arguments)};e=a.createElement(t),r=a.getElementsByTagName(t)[0];
e.async=1;e.src=c;r.parentNode.insertBefore(e,r);})(window,document,'script','https://via.batch.com/v2/bootstrap.min.js');

batchSDK('setup', {
  apiKey: "<your app's api key>",
  subdomain: '<your .via.batch.com subdomain>',
  authKey: '<your auth key>',
  dev: true, // REMOVE THIS FOR PRODUCTION
  vapidPublicKey: '<your vapid public key>',
  ui: {
    // UI Components configuration goes here. More info in the documentation.
  },
});
</script>

Upload required files

If you're running the SDK in HTTP/Multidomain mode, you can skip straight to Icons.

Service worker

By downloading and extracting the SDK's package, you should end up with a file named batchsdk-worker-loader.js

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: https://batch.com/batchsdk-worker-loader.js

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

Icons

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.

icons

Default icon

Configuration key: defaultIcon (optional).

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.

Small icon

Configuration key: smallIcon (optional).

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...).

SDK Configuration

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.

Development mode

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.

Forcing the HTTP mode (multiple subdomains/mixed content)

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.

Fully secure mode and development environments

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.

Integrating Batch with an existing Service Worker

As you may know, only one Service Worker per domain can be registered. 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:

  • Upload batchsdk-shared-worker.js at your website's root, and import it using importScripts("/batchsdk-shared-worker.js")
  • 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 batchsdk-shared-worker.js.

Asking the user to enable notifications

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: