Migrating from V4

Batch Web SDK v5 is a major release that introduces breaking changes from 4.x. This guide describes how to update the script on a website already using a previous version.

Upgrading the SDK version

To upgrade from v4 to v5, change the SDK version in two places:

1

Update your page script or tag manager

Replace:

https://via.batch.com/v4/bootstrap.min.js

With:

https://via.batch.com/v5/bootstrap.min.js

2

Update your service worker implementation

Download the new SDK files and update your service worker implementation.

• If you're using batchsdk-worker-loader.js, simply replace this file with the new one.
• If you added Batch in your custom service worker implementation, set BATCHSDK_MAJOR_VERSION's value to 5.

Push configuration

This version groups every push-related setting under a single push object at the root of the SDK configuration. The following keys moved from the top level of the configuration into push: vapidPublicKey, serviceWorker, smallIcon, defaultIcon and ui. They keep the same name and the same behavior; only their location changes.

apiKey, authKey, defaultDataCollection, migrations and enableHashFeatures are not push-related and stay at the top level of the configuration.

If you were previously doing something like this:

batchSDK('setup', {
  apiKey: 'YOUR_API_KEY',
  authKey: 'YOUR_AUTH_KEY',
  vapidPublicKey: 'YOUR_VAPID_PUBLIC_KEY',
  smallIcon: '/icon.png',
  defaultIcon: '/default-icon.png',
  serviceWorker: {
    automaticallyRegister: false,
    registration: navigator.serviceWorker.register('/my-service-worker.js'),
  },
  ui: {
    banner: { /* … */ },
  },
});

You should now do:

batchSDK('setup', {
  apiKey: 'YOUR_API_KEY',
  authKey: 'YOUR_AUTH_KEY',

  // Optional - push subscription and service worker related configuration.
  // Omitting `push` keeps push enabled with its defaults.
  push: {

    // Optional. Your VAPID public key, previously at the top level.
    vapidPublicKey: 'YOUR_VAPID_PUBLIC_KEY',

    // Optional. Icons displayed on the notification, previously at the top level.
    smallIcon: '/icon.png',
    defaultIcon: '/default-icon.png',

    // Optional. Service worker configuration, previously at the top level.
    // Keys and behavior are unchanged.
    serviceWorker: {
      automaticallyRegister: false,
      registration: navigator.serviceWorker.register('/my-service-worker.js'),
    },

    // Optional. Push subscription UI components, previously at the top level.
    ui: {
      banner: { /* … */ },
    },
  },
});

Data-Collect-only integration

If you only use Batch to collect events and profile data and do not send web push notifications, you can disable the push module entirely by setting push to false. In that case, no vapidPublicKey is required and no service worker is registered.

batchSDK('setup', {
  apiKey: 'YOUR_API_KEY',
  authKey: 'YOUR_AUTH_KEY',

  // Disables push subscription and service worker registration.
  push: false,
});

For more information, see:

• Uploading the Service Worker to a folder of your website
• Integrating Batch with an existing Service Worker

Removed configuration options

The following top-level options have been removed and no longer exist in v5. Remove them from your setup call; none of them has a replacement:

• dev: no longer used by the SDK.
• subdomain: only used by the HTTP / multidomain mode, which was removed in v3.
• sameOrigin: already deprecated since v3 and only threw an error on startup.
• safari : Safari push notifications

If you were previously doing something like this:

batchSDK('setup', {
  apiKey: 'YOUR_API_KEY',
  authKey: 'YOUR_AUTH_KEY',
  subdomain: 'webpush',
  dev: true,
  vapidPublicKey: 'YOUR_VAPID_PUBLIC_KEY',
});

You should now do:

batchSDK('setup', {
  apiKey: 'YOUR_API_KEY',
  authKey: 'YOUR_AUTH_KEY',
  push: {
    vapidPublicKey: 'YOUR_VAPID_PUBLIC_KEY',
  },
});

Safari push notifications

Legacy Safari APNS support has been removed. Since macOS Ventura (13.0), Safari 16 and higher implements the standard Web Push protocol, so Safari now goes through the same VAPID + service worker path as every other browser and no longer requires any Safari-specific configuration or push certificate.

The safari configuration key and the ISafariConfig type have been removed. Remove safari from your setup call.

If you were previously doing something like this:

batchSDK('setup', {
  apiKey: 'YOUR_API_KEY',
  authKey: 'YOUR_AUTH_KEY',
  safari: { 'https://example.com': 'web.com.example' },
  push: {
    vapidPublicKey: 'YOUR_VAPID_PUBLIC_KEY',
  },
});

You should now do:

batchSDK('setup', {
  apiKey: 'YOUR_API_KEY',
  authKey: 'YOUR_AUTH_KEY',
  push: {
    vapidPublicKey: 'YOUR_VAPID_PUBLIC_KEY',
  },
});

Existing Safari APNS subscribers are migrated transparently: on their next visit, they are re-subscribed to standard Web Push (VAPID) without a new permission prompt, as long as the notification permission was already granted.

Safari versions below 16 do not implement the PushManager API and no longer receive push notifications. The SDK still starts on these browsers, and events/profile data collection keeps working.

To see in detail what's precisely changed since v4, consult the changelog.