# SDK changelog

Changelog and release notes for the Batch SDK.

Minor and patch releases are automatically rolled out to pages. 

You can upgrade between major versions by changing the version of the script included in your webpage:

* Look for `https://via.batch.com/v4/bootstrap.min.js` in the script tag, where `v4` is the major version.
* Your service worker file also needs to be updated to match the tag's version, or the SDK might fail to start and/or display notifications.

{% updates format="short" %}
{% update date="2026-05-13" %}

## 4.3.2

***

**Profile**

* Fixed string array attribute size limits not being enforced for `addToArray` and `removeFromArray`.

**User**

* Fixed a regression from 4.0 where tag collections compatibility was incorrectly limited to 25 tags on the MEP.
  {% endupdate %}

{% update date="2026-04-10" %}

## 4.3.1

***

**User**

* Fixed a race condition in installation data synchronization on MEP that could cause attribute changes to be lost when simultaneous editor calls were made.
  {% endupdate %}

{% update date="2026-04-09" %}

## 4.3.0

***

**Profile**

* Added `setTopicPreferences` to the `IProfileDataEditor` interface.
* Added `addToTopicPreferences` to the `IProfileDataEditor` interface.
* Added `removeFromTopicPreferences` to the `IProfileDataEditor` interface.
  {% endupdate %}

{% update date="2025-03-04" %}

## 4.2.1

***

**Profile**

* Fixed a rare issue where users were not properly taken out of profile probation.
  {% endupdate %}

{% update date="2025-11-25" %}

## 4.2.0

***

**Profile**

* Strengthened custom user identifier validation on the `identify` API to avoid unintended values.
* Profile string attributes now support up to 300 characters for the Customer Engagement Platform (CEP). The limit for the Mobile Engagement Platform (MEP) remains 64 characters. Attributes set via `IProfileDataEditor.setAttribute()` longer than 64 characters only apply to CEP.
* Event string attributes now support up to 300 characters for the Customer Engagement Platform (CEP). The limit for the Mobile Engagement Platform (MEP) remains 200 characters. Attributes set via `trackEvent` longer than 200 characters only apply to CEP.
  {% endupdate %}

{% update date="2024-11-25" %}

## 4.1.2

***

**Core**

* Fixed an issue where internal subscription and unsubscription events could be sent with an old token.
  {% endupdate %}

{% update date="2024-07-24" %}

## 4.1.1

***

**Core**

* Fixed a rare issue where some data could be attached to the wrong profile due to a race condition when calling `profile.edit` or `trackEvent` right after `profile.identify`.
  {% endupdate %}

{% update date="2024-06-27" %}

## 4.1.0

***

**Core**

* Batch now starts even if the current browser does not support push messaging features.

**Service worker**

* Batch now detects when the service worker is not set up as expected and would break SDK functionality.
  {% endupdate %}

{% update date="2023-12-14" %}

## 4.0.0

***

This is a major release. See the [migration guide](/developer/sdk/web/advanced/3x-migration.md) for more info on what changed since 3.x.

**Core**

* Added built-in German translations.
* Added an optional `defaultDataCollection` configuration object to `setup`. This lets you enable the GeoIP back-end resolution for the user's `region` attribute, which is now disabled by default.
* Added an optional `migrations` configuration object to `setup`. This lets you disable data migrations to the new Batch user-centric data model, which is enabled by default.

**Service worker**

* Moved service worker configuration keys into a `serviceWorker` object.
* `automaticallyRegister` replaces `useExistingServiceWorker`. Set it to `false` to prevent Batch from automatically registering its worker. Default: `true`.
* `waitTimeout` replaces `serviceWorkerTimeout` and works the same way.
* `registration` lets Batch use a specific service worker registration. This can be a registration for a sub-scope that does not control the current page. Batch cannot verify that this service worker is valid for push notifications. Using `registration` requires `automaticallyRegister` to be `false`. If you do not set it, Batch defaults to `navigator.serviceWorker.ready`.
* `serviceWorkerPathOverride` has been removed. Manually register a service worker with your custom path and pass the promise to `registration`.

**User and profile**

In the past, data was siloed between platforms. Projects remove that limitation by introducing profiles. Each Project is associated with a unified user base made up of profiles. When users interact with any platform in a Project, their actions feed the associated profiles.

Web SDK v4 APIs are fully compatible with profiles and let you set attributes and events on omnichannel profiles.

* Removed `setCustomUserID`. Use `identify` instead.
* Removed `getCustomUserID`. There is no equivalent.
* Removed `setUserLanguage`. Use `setLanguage` instead.
* Removed `setUserRegion`. Use `setRegion` instead.
* Removed `editUserData`. Use `edit` instead.
* Removed `IUserDataEditor`. Use `IProfileDataEditor` instead.
* Removed `addTag`. Use `addToArray` instead.
* Removed `removeTag`. Use `removeFromArray` instead.
* Updated `trackEvent` parameters in `EventDataParams`:
  * Added support for `Array` and `Object` attribute types.
  * Replaced the optional `tag` attribute with `$tags` under the `attributes` object.
  * Replaced the optional `label` attribute with `$label` under the `attributes` object.
* Added the `profile` API to access the public profile module.
* Added `identify` under `IBatchProfile` as a replacement for `setCustomUserID`.
* Added `edit` under `IBatchProfile` as a replacement for `editUserData`.
* Added `setEmailAddress`. This requires a registered custom user ID.
* Added `setEmailMarketingSubscription`.
* Added `setLanguage` under `IProfileDataEditor` as a replacement for `setUserLanguage`.
* Added `setRegion` under `IProfileDataEditor` as a replacement for `setUserRegion`.
* Added `clearInstallationData` to clear all installation-related local data without affecting profile data.
  {% endupdate %}

{% update date="2023-04-18" %}

## 3.5.1

***

**Core**

* Batch now checks that `URL` works as expected to avoid breakage caused by bad polyfills.
  {% endupdate %}

{% update date="2023-02-23" %}

## 3.5.0

***

**Core**

* Changed the rules used to determine whether events should be sent immediately to Batch's back end or enqueued.

**Safari**

* Enabled iOS Web Push. This requires iOS 16.4 or later and the PWA to be installed as a standalone app.
  {% endupdate %}

{% update date="2022-11-22" %}

## 3.4.0

***

**Core**

* `subdomain` is now optional in the configuration object. Previously, omitting it could prevent notifications from showing their icon and image or opening the website on click.

**Safari**

* Batch now uses Web Push Protocol by default on Safari if a user is not already subscribed with APNS.

**UI**

* The `alert` UI component now supports a configurable extra button.
* Fixed an issue where the native UI component would not automatically resubscribe a user if the backoff duration had not elapsed.
  {% endupdate %}

{% update date="2022-07-08" %}

## 3.3.1

***

**Core**

* Improved validation of subscriptions before they are sent to Batch's servers.

**Safari**

* Fixed an issue where UI components could stay stuck in a loading state after a user granted or denied the push permission due to a Safari bug.
  {% endupdate %}

{% update date="2022-05-03" %}

## 3.3.0

***

**Core**

* Added `api.refreshServiceWorkerRegistration()` to resynchronize Batch's internal state with the current service worker registration.
* Added `api.doesExistingSubscriptionKeyMatchCurrent()` to check whether the current service worker registration's `applicationServerKey` matches the one Batch is configured with.

For more details, see the JSDoc.

**User**

* Optimized custom data synchronization when no data has been set.

**UI Components**

* Added the `showIfPermissionGranted` option to the Alert format. It defaults to `true`. Set it to `false` to prevent Alert from showing when the user has already granted notification permission, even if they are not subscribed to Batch. In that case, they will not be automatically resubscribed until you call `api.subscribe()`.
  {% endupdate %}

{% update date="2022-04-06" %}

## 3.2.0

***

**User**

* Added support for custom attributes and tags. See the [attributes documentation](/developer/sdk/web/legacy-documentation/custom-attributes-v3.md) for more info.
  {% endupdate %}

{% update date="2022-03-17" %}

## 3.1.0

***

**User**

* Added support for custom events. See the [events documentation](/developer/sdk/web/legacy-documentation/custom-events-v3.md) for more info.
  {% endupdate %}

{% update date="2021-12-17" %}

## 3.0.3

***

**Core**

* Enhanced compatibility of UI components with AMP pages using the Custom Elements polyfill.

**UI Components**

* Fixed a regression where Alert styling might not be applied properly.
  {% endupdate %}

{% update date="2021-12-08" %}

## 3.0.2

***

**Core**

* Worked around an issue where the SDK would not start on websites where `DOMContentLoaded` does not bubble.
  {% endupdate %}

{% update date="2021-11-17" %}

## 3.0.0 / 3.0.1

***

This is a major release. See the [migration guide](/developer/sdk/web/advanced/2x-migration.md) for more info on what changed since 2.x.

**Core**

* Added support for Safari push notifications. This requires additional dashboard and SDK configuration. See [Safari APNs setup](/developer/sdk/web/getting-started/safari-setup.md) for more info. Safari 12 or higher is required.
* Removed support for HTTP/Multidomain mode. `sameOrigin` is now deprecated and should be removed from the SDK configuration.
* `defaultIcon` and `smallIcon` are now optional and can be remotely configured from the Batch dashboard. Setting your own URLs is still supported.

**UI Components**

* If the `defaultIcon` image cannot be loaded, UI components now hide the image instead of showing the browser's broken image placeholder.
  {% endupdate %}

{% update date="2021-09-15" %}

## 2.2.1

***

**UI Components**

* Fixed an issue where Alert styling would not be applied properly.
  {% endupdate %}

{% update date="2021-09-09" %}

## 2.2.0

***

**Minimal browser versions**

* Edge (Legacy): 16
* Chrome: 55
* Firefox: 53
* Edge Chromium: 77

**Core**

* Added `getConfiguration()` to return a read-only copy of the SDK configuration for debugging.
* Improved logging of service worker registration errors.
* Added WebP images for Firefox.
* Fixed an issue where calling `setup` twice resulted in unexpected behavior.

**User**

* Improved type checking for `set` and `get` methods on user language, user region, and custom user ID:
  * They can no longer return `undefined`. They now always return `null` if not set.
  * They accept both `null` and `undefined` to unset their values.
* Updated `getInstallationID` so its definition matches the fact that it can never return `null`.

**UI Components**

* Fixed various theming issues on the `button` format.
* Added stable identifiers to multiple formats.
* Added a UI component that can display public identifiers such as Installation ID and Custom User ID. Show it with `batchSDK('ui.showPublicIdentifiers')`.
* Fixed a bug on Chrome where the native notification permission popup could be displayed twice if the user dismissed it.

**Messaging**

* Removed support for opening deeplinks in a pre-existing tab. A new tab now always opens.
  {% endupdate %}

{% update date="2018-11-22" %}

## 2.1.0

***

**Core**

* Reworked how the service worker is included. It is now automatically updated to the latest version.
* Removed async `importScripts`, which could cause issues in a shared service worker environment.

This release updates the service worker loader and shared worker implementation. Redownload `batchsdk-worker-loader.js` and deploy it to your website. If you use the shared worker, also download `batchsdk-shared-worker.js` and replace your existing `setupSharedBatchSDK` method with the new one.

If you rely on a shared service worker implementation, upgrade as soon as possible to stay compatible with recent Chrome and Firefox versions.
{% endupdate %}

{% update date="2018-10-23" %}

## 2.0.9

***

**Core**

* Fixed an issue where the registration token would not be immediately sent to the server if the service worker had been unregistered by a third party.
* Fixed an issue where calling Batch APIs before the SDK was ready could fail. Calls are now enqueued properly.

**UI Components**

* Fixed `popin` title configuration not being honored.
  {% endupdate %}

{% update date="2018-09-12" %}

## 2.0.8

***

**UI Components**

* Improved `button` rendering on mobile devices.
* Replaced header tags in UI components with simpler tags.
* Fixed `banner` left positioning.
* Fixed a Firefox bug where `alert` might never appear.
* Implemented `pushsubscriptionchange` in the service worker.
* Lazy loaded help images for browser permission re-opt-in.
* Added WebP help images for Chrome and optimized their PNG versions.
  {% endupdate %}

{% update date="2018-05-18" %}

## 2.0.6

***

* Fixed a link replacement bug in the `popin` UI component.
  {% endupdate %}

{% update date="2018-03-14" %}

## 2.0.5

***

* Fixed Alert buttons not showing up on Chrome 58 and lower.
  {% endupdate %}

{% update date="2018-03-09" %}

## 2.0.4

***

* Fixed RTL text alignment on the Alert format.
* Fixed UI components not working on Chrome 60 and lower.
  {% endupdate %}

{% update date="2017-12-08" %}

## 2.0.2 / 2.0.3

***

* Fixed an issue where opening a notification in Chrome would not do anything.
  {% endupdate %}

{% update date="2017-12-01" %}

## 2.0.1

***

* Fixed a registration bug with Chrome 62 and later in multidomain or insecure mode.
* Fixed an issue where the button preview push displayed incorrectly.
  {% endupdate %}

{% update date="2017-11-29" %}

## 2.0.0

***

* Added a new UI component format: Alert.
* The `button` UI component now supports configuring a preview of push notifications instead of a placeholder.
* The `button` UI component now supports changing the bell hover color with the `hoverForegroundColor` configuration key.
* Exposed the previously undocumented `ui` object in the SDK public API.
* Most UI components now support the `autoShow` configuration option, which prevents them from being shown automatically. Usage: `ui: { banner: { autoShow: false } }`.
* `banner.hideFor` now defaults to 7 days.
* Added `ui.show` and `ui.hide`, which let you control when UI components are displayed. Use them with `autoShow: false`. Example: `batchSDK("ui.show", "banner")`.
  {% endupdate %}
  {% endupdates %}


---

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

```
GET https://doc.batch.com/developer/sdk/web/sdk-changelog.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
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.