SDK version and migration guide

SPREEAI exposes version information for two different integration layers:

• Installable Web SDK: the @spreeai/web-sdk package used by storefront code.
• Hosted Try-On experience: the SPREEAI-managed web experience loaded by the SDK.

Do not treat these as the same version. A 3.x Web SDK can legitimately load a 1.x hosted experience.

Supported Web SDK versions

Version	Status
3.x	Supported. Use it for all new and existing integrations.
2.x	Deprecated. Upgrade to 3.x using Upgrading to v3.
1.x	Deprecated. The tryOnButton entry point still ships in 3.x for compatibility only.

Hosted-version status

The hosted staging experience publishes /sdk-version-manifest.json. The manifest identifies the current build, minimum supported build, compatibility contract, deprecation date, and the documentation links for migration and rollback.

The runtime reports a non-sensitive spreeai.sdk.version message to its host. It contains version and compatibility status only; it must not contain credentials or customer data.

Status	Meaning	Required action
current	The connected build matches the recommended build	Continue normal UAT
outdated	Supported, but below the recommended build	Schedule a staging upgrade
unsupported	Below the minimum supported build	Upgrade before release
ahead	Newer than the published recommendation	Hold production promotion and verify the intended channel
unavailable	The manifest could not be read	Continue the current session, then retry and escalate if persistent

A temporary manifest outage does not block the experience. It does block declaring a migration verified.

Compatibility window

The 2026-09 managed-host target keeps these integration contracts:

• partner entitlements, unchanged
• host messaging, unchanged
• installable Web SDK 3.x integration through init

The live staging manifest lists the minimum supported and target managed-host builds for this window. Check it before you upgrade.

Migration procedure

1. Record the current installable SDK version and hosted-build version. For the installable Web SDK, read the installed version from your lockfile (package-lock.json, yarn.lock, or pnpm-lock.yaml), or from the version in the CDN URL if you load the SDK from unpkg.
2. Record the exact staging credentials, entitlement decisions, and rollback target.
3. Upgrade only in staging.
4. Replace deprecated tryOnButton usage with init plus sdk.renderTryOnButton.
5. Replace legacy single garmentId usage with the garments array.
6. When moving the installable Web SDK from 2.x to 3.x, apply the breaking changes in Upgrading to v3: remove partnerId from init, remove features.loadingScreen, remove any sdk.renderSizingButton calls, and allow the https://vton.spreeai.com origin if you restrict frame origins.
7. Run the integration UAT checklist.
8. Compare authentication, readiness, latency, error rate, and analytics against the baseline.
9. Request production promotion through the managed release process. A green PR or staging test is not production proof.

Rollback

1. Stop the rollout if authentication, entitlement, garment, or purchase behavior regresses.
2. Restore the last verified SDK package and managed-host image together when the compatibility contract requires it.
3. Re-run the smoke path and confirm the previous build in the version manifest.
4. Keep the failed release evidence; do not delete logs or correlation IDs.
5. Open an incident if rollback does not restore the baseline.

Never improvise a production rollback from an unverified local build.