Migrating from 2.x

This upgrade is required. The endpoints Web SDK 2.x uses now answer 426 Upgrade Required. Sites running 2.x keep showing what they cached but receive no further updates until you deploy 3.0.1 or later.

1. Update the package

npm install @stringboot/web-sdk@^3.0.1

2. Use a Client Token

Pass your App’s Client Token (sb_...) as apiToken. Create one in the dashboard (see API Tokens). The token now travels in the URL path, not in an X-API-Token or Authorization header. A Figma Plugin Token, or a revoked or expired token, gets 401 invalid_token.

3. Review the behaviour changes

`initialize()` resolves earlier

This is the change most likely to affect your code. With a Catalog stored from an earlier visit, initialize() now resolves as soon as that Catalog is applied; the /languages and version checks finish in the background. On a first visit it still waits for the download. If your code assumes “initialize() resolved” means “synced with the server”, wait for the start-up checks explicitly:

await StringBoot.initialize({ apiToken: 'sb_YOUR_CLIENT_TOKEN' });
await StringBoot.waitForStartupSync();   // never rejects

Errors found after start-up, such as a rejected token, arrive through onSyncError. In React, useStringBoot().error reports them too.

const off = StringBoot.onSyncError((error) => {
  if (error.code === 'INVALID_TOKEN') showTokenBanner();
});

Other changes

Area	What changed
Device-ID	Every request carries a `Device-ID`, generated and stored by the SDK. Pass `deviceId` only to use your own.
FAQs	Come with the Catalog. Remove `StringBoot.FAQ.initialize(...)`; it’s accepted but does nothing once the SDK is initialized.
Experiments	Bucketed in the browser with the same function the server used. 2.x didn’t send a Device-ID, so web users get a new one and may land in a different variant once; pass your previous user id as `deviceId` if you need continuity. `onExperimentsAssigned` still works and is now called with `{}` when experiments stop. Add `onExposure` to report exposures.
Periodic checks	New: every 60 seconds by default (`refreshInterval`), paused while the tab is hidden.
Fallback	A key missing from the selected language falls back to the App’s default language before `??key??`.
Escapes	`\n`, `\t`, `\r`, `\"`, `\'` and `\\` in string values are unescaped, as on mobile. Use `white-space: pre-line` to show line breaks.
Language codes	Matched exactly as listed in the dashboard (for example `pt-BR`), no longer cut to two letters. `ActiveLanguage` gains `nativeName` and `direction`.
React	`useString` and `useStrings` render the cached value on their first render instead of briefly showing `??key??`.
Integrity checks	`enableIntegrityCheck` is accepted and ignored.

Removed types

MetaResponse, DeltaResponse, CatalogResponse, ApiResponse, SyncMetadata, CachedString, FAQMetaResponse, FAQDeltaResponse and FAQCatalogResponse. Use Catalog, LanguagesResponse and CurrentVersionResponse instead.

What happens to returning visitors

On the first start, 3.0 deletes the data 2.x stored in the browser and downloads the strings once.

Checklist

@stringboot/web-sdk is 3.0.1 or later
apiToken is a Client Token starting with sb_
Code that needs fresh server data waits for waitForStartupSync()
Errors after start-up are handled with onSyncError (or useStringBoot().error)
Analytics code handles an empty assignments object
StringBoot.FAQ.initialize(...) calls are removed
A first visit shows your strings, and an edit in the dashboard appears within about two minutes

Getting Started

Android SDK

iOS SDK

Web SDK

Dashboard

1. Update the package

2. Use a Client Token

3. Review the behaviour changes

`initialize()` resolves earlier

Other changes

Removed types

What happens to returning visitors

Checklist

​1. Update the package

​2. Use a Client Token

​3. Review the behaviour changes

​initialize() resolves earlier

​Other changes

​Removed types

​What happens to returning visitors

​Checklist

1. Update the package

2. Use a Client Token

3. Review the behaviour changes

`initialize()` resolves earlier

Other changes

Removed types

What happens to returning visitors

Checklist