Integration operations center

Use this page as the operational source of truth for a SPREEAI integration. It covers supported partner entry points, verification, failure isolation, UAT, and escalation.

Choose the supported path

Need	Supported path	Keep out of the browser
Add Try-On or Fit + Size to a web storefront	@spreeai/web-sdk with init and the SDK render methods	Secret credentials and service tokens
Add SPREEAI to Shopify	Install the managed Shopify app and complete its guided onboarding	Manual store credentials or private app tokens
Run the hosted Try-On experience	Use the SPREEAI-managed host supplied for your environment	Direct calls to internal generation services
Process garments with Gemini-assisted automation	Submit garments through the supported SPREEAI ingestion path	Gemini API keys, model names, prompts, and internal endpoints

Gemini is an internal implementation detail of managed ingestion. Partners should not call Gemini directly. This boundary keeps model credentials server-side and lets SPREEAI change the processing implementation without forcing a partner migration.

Web implementation example

import { init } from "@spreeai/web-sdk";

const sdk = await init({
  clientId: "your-client-id",
  partnerId: "your-partner-id",
});

if (!sdk) throw new Error("SPREEAI authentication failed");

await sdk.renderTryOnButton({
  elementId: "spreeai-try-on",
  garments: [{ garmentId: "partner-garment-id" }],
  events: {
    onTryOnButtonClick: (event) => analytics.track("spreeai_try_on_started", event),
  },
});

Use garments for new integrations. The legacy garmentId and tryOnButton entry points remain compatibility paths but are deprecated.

Failure-resolution tree

1. The SDK does not initialize
   • Confirm clientId and partnerId belong to the same environment.
   • Confirm the browser is using the approved SPREEAI origins for that environment.
   • Check the network response for the authentication handshake. Do not paste tokens into a ticket.
2. The button renders but the experience does not open
   • Verify the target element ID is unique and present before the render call.
   • Confirm Content Security Policy and popup/iframe rules allow the supplied SPREEAI host.
   • Capture the SDK version status and browser console error.
3. A garment cannot be used
   • Confirm the garment and selected variant are in a Ready state.
   • Resolve image, SKU, metadata, or QA blockers in the Partner Portal or Shopify workflow.
   • Retry only after the blocker is cleared; repeated retries do not repair source data.
4. The experience opens but generation fails
   • Preserve the request/correlation ID and timestamp.
   • Confirm the user image and garment passed preflight.
   • Retry once after a transient service failure. For a repeated failure, escalate with non-sensitive evidence.
5. The installed or hosted version is outdated
   • Read the version and migration guide.
   • Upgrade in staging, complete the UAT checklist below, then use the normal managed release path.

UAT checklist

• Test only with staging credentials and staging garments.
• Verify the expected package and feature entitlements.
• Confirm single-garment and multi-garment launches.
• Confirm selected variants exist and are Ready.
• Validate desktop and mobile behavior in supported browsers.
• Validate loading, empty, timeout, and service-error states.
• Validate Add to Cart only when the feature is enabled.
• Confirm analytics events do not include tokens or raw user images.
• Confirm the runtime version is current and above the minimum supported version.
• Capture the exact build, test evidence, and rollback target before requesting production promotion.

Evidence for escalation

Include the partner/store identifier, environment, UTC timestamp, SDK or hosted-build version, browser/device, garment ID, correlation ID, expected result, actual result, and reproducible steps. Redact access tokens, cookies, user photos, and customer personal information.

Open the Partner Portal Help & support workflow and use the support channel assigned to your account. For an active incident, include service-health evidence and the last known successful timestamp.