AutoViz SDK Integration Guide

Overview

The AutoViz SDK embeds 3D product tools (Viewer, Configurator, Catalog, See in My Space, AR Try-On) into your storefront. There are two ways to wire it up:

Slots (recommended) — declare placeholders in your HTML and let your AutoViz integration config decide what goes in each. Centralised, admin-editable, no per-page button markup.
Manual buttons — author each class="autoviz" button or container directly in your HTML with data-* attributes. Use this when you need page-specific behaviour the slot config doesn't cover.

Both approaches share the same underlying SDK script and the same tools.

Quick Start

Add the SDK script to your page once:

<script src="https://sdk-v2.autoviz.io" defer></script>

The defer attribute ensures the script loads without blocking page rendering and executes after the DOM is ready.

1. Slots (recommended)

Place inert containers on your page that the SDK fills with tools at runtime. The mapping between slot names and tool components lives in your AutoViz integration config — so you can change buttons, swap tools, or rename groups without redeploying your storefront.

Declaring a slot

<div data-autoviz-slot="wheel-builder-catalog"></div>

That's the whole markup contract. The SDK reads the integration config delivered for your origin, finds the entry keyed wheel-builder-catalog, and renders the configured components inside the container.

How slots are configured

Each slot entry is a list of components — buttons that launch tools, embedded iframes, or other affordances. Components are configured server-side by your AutoViz operator account and delivered to the SDK with your sdk-init response. A typical slot entry looks like:

{
  "slots": {
    "wheel-builder-catalog": {
      "components": [
        {
          "id": "wheel-builder-catalog",
          "tool": "catalog",
          "type": "iframe",
          "query_params": "brand_id=5D2D01E1&custom_mode=1"
        }
      ]
    }
  }
}

Per-slot overrides may be declared inline on the slot element via data-params:

<div data-autoviz-slot="product-3d-tools"
     data-params="group=apex-pro&select_field=finish_name&select_current=chrome">
</div>

The SDK merges these with the slot's config-defined parameters.

Why slots first

No per-page HTML to maintain. A new tool or button rolls out by editing your integration config — no storefront redeploy.
Consistent across surfaces. The same slot name renders identically on every page that declares it (product detail, listing card, cart, etc).
Tool swap without code changes. Switch a slot from Catalog to Configurator (or vice versa) by changing the config.

Styling slots

Slot containers expose data-autoviz-slot="<name>" after rendering — target them from your stylesheet:

[data-autoviz-slot='product-actions'] {
  display: flex;
  gap: 0.5rem;
}

The SDK also sets data-tool="<tool>" on every button it renders, so you can style by tool:

[data-tool='configurator'] {
  background: #000;
  color: #fff;
}

2. Manual buttons

When you need page-specific behaviour or the slot config doesn't cover your case, author the element directly with class="autoviz" and data-* attributes.

Basic example

<button class="autoviz my-button-class"
        data-tool="viewer"
        data-group="super-model-series-x"
        data-select-field="finish_name"
        data-select-current="gloss-black"
        data-display-mode="fullscreen"
        data-fullscreen-avoid="#header">
  VIEW IN 3D
</button>

Style with your own CSS — the SDK won't modify your HTML.

Core attributes

Attribute	Type	Required	Description	Example
`data-tool`	string	Yes	Tool to launch (viewer, configurator, sims, arto, catalog)	`data-tool="viewer"`
`data-part-id`	number	Optional	AutoViz part ID	`data-part-id="12345"`
`data-variant-id`	number	Optional	Specific variant ID	`data-variant-id="67890"`
`data-group`	string	Optional	Product group identifier for selections	`data-group="series-z"`
`data-select-field`	string	Optional	Field name for selections	`data-select-field="finish_name"`
`data-select-current`	string	Optional	Current selection value	`data-select-current="chrome"`

Setting data-part-id and/or data-variant-id takes precedence over data-group + data-select-* selections.

UI customization

Attribute	Type	Description	Example
`data-display-mode`	string	Display mode (modal, fullscreen, fillparent)	`data-display-mode="fullscreen"`
`data-fullscreen-avoid`	string	CSS selector to avoid overlapping	`data-fullscreen-avoid="#header"`
`data-theme`	string	UI theme preference	`data-theme="dark"`
`data-theme-toggle`	string	Show theme toggle button	`data-theme-toggle="0"`
`data-background`	string	Show background (`0` for transparent)	`data-background="1"`
`data-primary-color`	string	Primary UI color (hex without `#`)	`data-primary-color="FF0000"`
`data-hide-nav`	string	Hide navigation controls	`data-hide-nav="1"`
`data-hide-close`	string	Hide close button	`data-hide-close="1"`
`data-config-button`	string	Show configurator button in viewer	`data-config-button="1"`

Launch behavior

Attribute	Type	Description	Example
`data-auto-launch`	string	Auto-launch tool on page load without requiring a click (`true` or `1`)	`data-auto-launch="true"`
`data-launch-params`	string	Additional query params passed to the tool URL (URL query string format)	`data-launch-params="brand_id=2683&chh=1"`

Attribute	Type	Description	Example
`data-launch-params` with `brand_id`	string	Filter catalog/viewer to a specific brand by numeric ID	`data-launch-params="brand_id=2683"`
`data-launch-params` with `brand_ids`	string	Filter to multiple brands (dot-separated IDs)	`data-launch-params="brand_ids=1.2.3"`

Part specifications [beta]

Use data-spec-{name} attributes to pass wheel sizing and fitment data. See Part Specification for full documentation.

<button class="autoviz"
        data-tool="configurator"
        data-spec-front-wheel="diameter=22&width=10&offset=25"
        data-spec-rear-wheel="diameter=22&width=12&offset=30">
  Configure Wheels
</button>

A leading ? in spec values is automatically stripped — "?diameter=22" and "diameter=22" are equivalent.

Valid tool values

Tool Value	Description
`viewer`	3D Viewer
`configurator`	Configurator
`sims`	See In My Space
`arto`	AR Try-On
`catalog`	Catalog browser

Valid mode values

Mode	Description
`modal`	Opens in modal dialog (default)
`fullscreen`	Opens in fullscreen overlay
`fillparent`	Fills parent container

Preventing button flash (FOUC)

The SDK validates that 3D models exist before showing buttons. To prevent buttons from flashing before validation completes, pre-hide them. The SDK uses visibility and opacity for showing/hiding — do not use display: none as the SDK cannot override it.

Method 1 — CSS rule (recommended)

<style>
  .autoviz {
    visibility: hidden;
    opacity: 0;
  }
  /* SDK adds autoviz-visible class which overrides these */
</style>

Method 2 — Inline style

<button class="autoviz my-button"
        style="visibility: hidden; opacity: 0;"
        data-tool="viewer"
        data-group="my-wheel">
  View in 3D
</button>

Method 3 — SDK hidden class

<button class="autoviz autoviz-hidden my-button"
        data-tool="viewer"
        data-group="my-wheel">
  View in 3D
</button>

SDK visibility classes

Class	Description
`autoviz-hidden`	Element is hidden (height: 0, opacity: 0, visibility: hidden)
`autoviz-visible`	Element is visible (opacity: 1, visibility: visible)
`autoviz-disabled`	Element is dimmed and non-interactive

Do NOT use:

/* This will NOT work — SDK cannot override display */
.autoviz { display: none; }

Complete examples

Example 1 — Minimal button

<button class="autoviz my-button-class"
        data-tool="viewer">
  View in 3D
</button>

Example 2 — Product configuration

<div class="autoviz my-custom-class"
     data-tool="viewer"
     data-group="series-z"
     data-select-field="finish_name"
     data-select-current="chrome"
     data-display-mode="fullscreen"
     data-fullscreen-avoid=".site-header">
  <img src="wheel-thumb.jpg" alt="Configure Wheel">
  <span>Customize Your Wheel</span>
</div>

Example 3 — Catalog auto-launch (no button)

<div class="autoviz"
     data-tool="catalog"
     data-auto-launch="true"
     data-launch-params="brand_id=2683&catalog_hide_header=1&catalog_link_to_viewer=1">
</div>

This embeds and auto-launches the catalog on page load — no button is rendered, the tool opens immediately.

Example 4 — Customized UI

<button class="autoviz my-button"
        data-tool="viewer"
        data-group="wheels"
        data-theme="dark"
        data-primary-color="FF6B6B"
        data-hide-nav="1"
        data-config-button="1">
  View in 3D
</button>

Dynamic value resolution

Both slot data-params and manual data-* attributes accept dynamic placeholders that resolve from the current page URL at click time.

Query parameter values (`?`)

Use ?param_name to pull values from URL query parameters:

<!-- URL: https://example.com/wheels?finish=chrome&color=red -->
<button data-select-current="?finish">View</button>
<!-- Resolves to: data-select-current="chrome" -->

<button data-theme="?theme">View</button>
<!-- If ?theme=dark in URL, resolves to: data-theme="dark" -->

Path segment values (`/`)

Use /index to pull values from URL path segments (0-based):

<!-- URL: https://example.com/wheels/series-a/finish-1 -->
<button data-group="/1">View</button>
<!-- Resolves to: data-group="series-a" -->

<button data-select-current="/2">View</button>
<!-- Resolves to: data-select-current="finish-1" -->

Supported attributes

Dynamic values work with these attributes:

data-group
data-part-id
data-variant-id
data-select-current
data-select-field
data-spec-* (see Part Specification)

Combined example

<!-- URL: https://mystore.com/products/wheels/12345?finish=chrome&size=20 -->

<!-- Query param resolution -->
<button data-select-current="?finish">View</button>
<!-- Result: data-select-current="chrome" -->

<!-- Path segment resolution -->
<button data-group="/1">View</button>
<!-- Result: data-group="wheels" -->

<button data-part-id="/2">View</button>
<!-- Result: data-part-id="12345" -->

Overview​

Quick Start​

1. Slots (recommended)​

Declaring a slot​

How slots are configured​

Why slots first​

Styling slots​

2. Manual buttons​

Basic example​

Core attributes​

UI customization​

Launch behavior​

Brand & catalog filters​

Part specifications [beta]​

Valid tool values​

Valid mode values​

Preventing button flash (FOUC)​

Method 1 — CSS rule (recommended)​

Method 2 — Inline style​

Method 3 — SDK hidden class​

SDK visibility classes​

Complete examples​

Example 1 — Minimal button​

Example 2 — Product configuration​

Example 3 — Catalog auto-launch (no button)​

Example 4 — Customized UI​

Dynamic value resolution​

Query parameter values (?)​

Path segment values (/)​

Supported attributes​

Combined example​