> For the complete documentation index, see [llms.txt](https://doc.batch.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://doc.batch.com/developer/sdk/web/advanced/4x-migration.md).

# 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:

{% stepper %}
{% step %}

#### 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
```

{% endstep %}

{% step %}

#### Update your service worker implementation

Download the new [SDK files](https://download.batch.com/sdk/web/BatchSDK-web-5.0.0.zip) 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`.
  {% endstep %}
  {% endstepper %}

### 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:

```js
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:

```js
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.

```js
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](https://doc.batch.com/developer/sdk/web/advanced/declare-path-service-worker#uploading-the-service-worker-to-a-folder-of-your-website)
* [Integrating Batch with an existing Service Worker](https://doc.batch.com/developer/sdk/web/advanced/integrating-batch-with-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](#safari-push-notifications "mention")

If you were previously doing something like this:

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

You should now do:

```js
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:

```js
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:

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

{% hint style="info" %}
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.
{% endhint %}

{% hint style="warning" %}
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.
{% endhint %}

To see in detail what's precisely changed since v4, consult the [changelog](https://doc.batch.com/developer/sdk/web/sdk-changelog).


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:

```
GET https://doc.batch.com/developer/sdk/web/advanced/4x-migration.md?ask=<question>&goal=<endgoal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.