Developer overview
Category: Developer. Status: Normative.
Vertcie provides supported interfaces for displaying and interacting with published configurable products. Developer integrations are limited to the browser runtime and public runtime API.
Integration surfaces
| Need | Interface |
|---|---|
| Embed a complete configurable product | <vertcie-client> browser component |
| Build a custom product viewer or selector | Browser runtime SDK |
| Build a custom Figma/Redux/Three.js configurator from Runtime data | Runtime custom UI guide |
| Retrieve published files, models, images, or resolved selections | Public runtime HTTP API |
Developer applications should use the browser runtime or public HTTP API and must not depend on the Vertcie authoring application or its implementation details.
Core identifiers
| Identifier | Use |
|---|---|
publishedFileId | Permanent identity for one published product/configurator across updates |
signature | Resolves an external configuration representation |
| Option/shader IDs | Preserve selections independently of display labels |
| Publication revision | Immutable numbered release beneath a Published File ID |
| Selection revision ID | Identifies an append-only selection update |
| Job ID | Tracks asynchronous render or asset work |
Store stable identifiers. Treat signed URLs as temporary delivery capabilities and request replacements when they expire.
Typical published-product flow
Load published file → present options → resolve selection
→ update viewer → request images or derived assets when needed- Configure the documented runtime endpoint and a public API key.
- Load a
publishedFileIdwith eitheruseLatest: trueor an exactrevision. - Build controls from the returned option and shader identifiers.
- Resolve selections through the runtime helper or supported endpoint.
- Apply visibility, material, and transform results together.
- Handle loading, empty, unauthorized, unavailable, and expired-asset states.
Use latest for customers who should receive activated updates without changing configuration. Pin a numbered revision when reproducible content is required. A normal product update creates another immutable revision beneath the same Published File ID; it does not require a new customer-facing ID.
Compatibility expectations
- Pin the runtime version used by the application.
- Feature-detect optional capabilities.
- Accept additional JSON response fields without failing.
- Do not construct asset paths or infer undocumented identifiers.
- Test representative published products before upgrading.
- Keep API keys origin-restricted and never expose privileged credentials.
Continue with authentication.md, runtime-sdk.md, public-runtime-api.md, or the comprehensive Runtime custom UI guide.