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 2.x Web SDK can legitimately load a 1.x hosted experience.

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 entitlement lookup at v1/partner/entitlements
• host messaging contract postMessage-v1
• installable Web SDK 2.x integration through init

The minimum managed-host build for this window is 1.0.2. The target release is 1.0.3. Verify the live staging manifest before relying on either value.

Migration procedure

1. Record the current installable SDK version and hosted-build version.
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. Run the integration UAT checklist.
7. Compare authentication, readiness, latency, error rate, and analytics against the baseline.
8. 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.