Customization Data

Overview

When a user customizes a product in the AutoViz configurator and applies their selection, the customization data is saved to localStorage and can be posted to the parent window. This allows your application to capture the complete configuration state including selected finishes, colors, and a rendered image.

localStorage Persistence

Customization data is automatically saved to localStorage using the following key format:

saved-wheel-config_{group}

Where {group} is the product group identifier (e.g., maxim-2p, series-z).

Example key: saved-wheel-config_apex-pro

This allows your application to:

Restore user configurations across sessions
Pre-populate cart/checkout with saved configurations
Display saved configurations in product galleries

Data Structure

Complete Example

{
  "data_url": "data:image/webp;base64,UklGRmyzAwBXRUJQVlA4WAoAAA...A==",
  "share_url": "https://app.autoviz.io/configurator/100001/200001?hideBackButton=true&showSaveButton=true&hideFilters=true&hideDesigns=true&hideSaveButton=true&hideExportButton=true&hideSeeMySpaceButton=true&hideTryOnArButton=true&wheel_selector=0&see_in_my_space=true&try_on_in_ar=false&hide_quote_request=true&client_view=true&hide_back_button=false&hide_upload_image_swatch=1&theme=light&brand=Velocity&barrel_t=solid&barrel_c=black&barrel_s=satin&hardware_t=solid&hardware_s=gloss&hardware_c=black&cap_t=solid&cap_s=satin&cap_c=black&face_group_t=tint&face_group_b=brushed&face_group_s=satin&face_group_c=phoenix-gold",
  "id": 100001,
  "mapped_id": "apex-pro",
  "part_number": null,
  "part_key": "1/100001/200001",
  "part_type": "Wheel",
  "display_name": "APEX",
  "brand": "Velocity Wheels",
  "part_variant": {
    "display_name": "Exposed Hardware",
    "id": 200001,
    "part_number": null
  },
  "sub_parts": {
    "center": {
      "part_type_id": 42,
      "part_type_display_name": "Wheel Face",
      "part_id": 100002,
      "part_key": "42/100002/200002",
      "part_number": "",
      "display_name": "APEX Faces",
      "brand": "Velocity Wheels",
      "part_variant_id": 200002,
      "part_variant_display_name": "Exposed Hardware Face",
      "customizations": {
        "face": {
          "type": "tint",
          "base": "brushed",
          "sheen": "satin",
          "color": {
            "name": "phoenix-gold",
            "hex": "#ffc600",
            "is_custom": false,
            "type": "color-tint-signature"
          }
        },
        "face_text": {
          "type": "tint",
          "base": "brushed",
          "sheen": "satin",
          "color": {
            "name": "phoenix-gold",
            "hex": "#ffc600",
            "is_custom": false,
            "type": "color-tint-signature"
          }
        }
      }
    },
    "hardware": {
      "part_type_id": 73,
      "part_type_display_name": "Wheel Hardware",
      "part_id": 100003,
      "part_key": "73/100003/200003.model_src_rear",
      "part_number": "",
      "display_name": "Velocity Standard Hardware",
      "brand": "Velocity Wheels",
      "part_variant_id": 200003,
      "part_variant_display_name": "Exposed Hardware",
      "customizations": {
        "hardware": {
          "type": "solid",
          "sheen": "gloss",
          "color": {
            "name": "black",
            "hex": "#000000",
            "is_custom": false,
            "type": "color-solid-signature"
          }
        }
      }
    },
    "cap": {
      "part_type_id": 6,
      "part_type_display_name": "Center Cap",
      "part_id": 100004,
      "part_key": "6/100004/200004",
      "part_number": "",
      "display_name": "APEX Caps",
      "brand": "Velocity Wheels",
      "part_variant_id": 200004,
      "part_variant_display_name": "Offset Cap",
      "customizations": {
        "cap": {
          "type": "solid",
          "sheen": "satin",
          "color": {
            "name": "black",
            "hex": "#000000",
            "is_custom": false,
            "type": "color-solid-signature"
          }
        }
      }
    },
    "barrel": {
      "part_type_id": 40,
      "part_type_display_name": "Wheel Barrel",
      "part_id": 100005,
      "part_key": "40/100005",
      "part_number": "",
      "display_name": "APEX Barrel",
      "brand": "Velocity Wheels",
      "customizations": {
        "barrel": {
          "type": "solid",
          "color": {
            "name": "black",
            "hex": "#000000",
            "is_custom": false,
            "type": "color-solid-signature"
          },
          "sheen": "satin"
        }
      }
    },
    "brake": {
      "part_type_id": 2,
      "part_type_display_name": "Brake",
      "part_id": 100006,
      "part_key": "2/100006/200006",
      "part_number": "",
      "display_name": "Standard Brake",
      "brand": "AutoViz",
      "part_variant_id": 200006,
      "part_variant_display_name": "Brake",
      "customizations": {}
    },
    "lugs": {
      "part_type_id": 72,
      "part_type_display_name": "Wheel Lugs",
      "part_id": 100007,
      "part_key": "72/100007",
      "part_number": "",
      "display_name": "Base Lug",
      "brand": "AutoViz",
      "customizations": {}
    }
  },
  "configuratorURL": {
    "queryParams": "https://app.autoviz.io/configurator/100001/200001?hideBackButton=true&showSaveButton=true&...",
    "productSku": "apex-pro"
  },
  "timestamp": 1769093051042
}

Field Reference

Top-Level Fields

Field	Type	Description
`data_url`	string	Base64-encoded webp image of the 3D render
`share_url`	string	Full configurator URL with all finish parameters encoded
`id`	number	AutoViz internal part ID
`mapped_id`	string \| null	Brand's internal SKU or product identifier
`part_number`	string \| null	Part number if available
`part_key`	string	Unique key in format `partTypeId/partId` or `partTypeId/partId/variantId`
`part_type`	string	Display name of the part type (e.g., "Wheel")
`display_name`	string	Product display name
`brand`	string	Brand name
`part_variant`	object \| null	Selected variant information (if applicable)
`sub_parts`	object	Record of component parts with their customizations
`configuratorURL`	object	URLs for linking back to the configurator
`timestamp`	number	Unix timestamp (milliseconds) for cache management

Part Variant Object

When a variant is selected, the part_variant object contains:

Field	Type	Description
`display_name`	string	Variant display name
`id`	string \| number	Variant ID
`part_number`	string \| null	Variant part number

Sub-Parts Object

The sub_parts object is keyed by part handle (e.g., center, barrel, cap, hardware). Each sub-part contains:

Field	Type	Description
`part_type_id`	number	Part type identifier
`part_type_display_name`	string	Human-readable part type name
`part_id`	number	Part identifier
`part_key`	string	Unique part key
`part_number`	string	Part number
`display_name`	string	Part display name
`brand`	string	Part brand
`part_variant_id`	string \| undefined	Variant ID if applicable
`part_variant_display_name`	string \| undefined	Variant name if applicable
`customizations`	object	Mesh-level finish customizations

Customizations Object

Each mesh within a sub-part can have its own customization. The customizations object is keyed by mesh name (e.g., face, face_text, barrel, cap):

Field	Type	Description
`type`	string	Finish type: `solid`, `metallic`, `tint`, or `preconfig`
`base`	string \| undefined	Base material (only for `tint` type): `raw-milled`, `polished`, `brushed`
`sheen`	string	Sheen level: `gloss`, `satin`, `matte`
`color`	object	Color details

Color Object

Field	Type	Description
`name`	string	Color identifier (e.g., `phoenix-gold`, `black`)
`hex`	string	Hex color code (e.g., `#ffc600`)
`is_custom`	boolean	Whether this is a custom color (from color picker)
`type`	string	Color category (e.g., `color-tint-signature`, `color-solid-signature`)

Configurator URL Object

Field	Type	Description
`queryParams`	string	Full URL with all configuration parameters
`productSku`	string	Product SKU/group identifier

Reading from localStorage

// Get the saved configuration for a specific product group
const groupName = 'apex-pro';
const storageKey = `saved-wheel-config_${groupName}`;
const savedConfig = localStorage.getItem(storageKey);

if (savedConfig) {
  const configData = JSON.parse(savedConfig);

  // Access the rendered image
  const imageDataUrl = configData.data_url;

  // Access the share URL for linking back to configurator
  const shareUrl = configData.share_url;

  // Access product info
  const productName = configData.display_name;
  const brand = configData.brand;

  // Access sub-part customizations
  const faceCustomization = configData.sub_parts.center?.customizations?.face;
  if (faceCustomization) {
    console.log('Face finish:', faceCustomization.type);
    console.log('Face color:', faceCustomization.color?.name);
  }
}

Finish Type Reference

Type	Description	Steps
`solid`	Opaque paint finish	sheen, color
`metallic`	Metallic paint finish	sheen, color
`tint`	Transparent tint over base material	base, sheen, color
`preconfig`	Pre-configured finishes (e.g., chrome plating)	preconfig selection only

Migration from SDK v1

SDK v2 introduces a restructured customization data format with richer part metadata and hierarchical organization. This section highlights the key differences for clients migrating from SDK v1.

SDK v1 (Legacy) Format

{
  "wheelDetails": [
    {
      "displayName": "barrel",
      "selectedName": "Champagne / Gloss",
      "selectedColor": null,
      "colorHex": null,
      "finishName": null
    },
    {
      "displayName": "cap",
      "selectedName": "Sand / Gloss",
      "selectedColor": null,
      "colorHex": null,
      "finishName": null
    },
    {
      "displayName": "cap_ring",
      "selectedName": "Sand / Gloss",
      "selectedColor": null,
      "colorHex": null,
      "finishName": null
    },
    {
      "displayName": "cap_text",
      "selectedName": "Ebony / Gloss",
      "selectedColor": null,
      "colorHex": null,
      "finishName": null
    },
    {
      "displayName": "face",
      "selectedName": "Sand / Metallic",
      "selectedColor": null,
      "colorHex": null,
      "finishName": null
    },
    {
      "displayName": "face_milling",
      "selectedName": "Sand / Metallic",
      "selectedColor": null,
      "colorHex": null,
      "finishName": null
    },
    {
      "displayName": "face_text",
      "selectedName": "Sand / Metallic",
      "selectedColor": null,
      "colorHex": null,
      "finishName": null
    },
    {
      "displayName": "face_window",
      "selectedName": "Sand / Metallic",
      "selectedColor": null,
      "colorHex": null,
      "finishName": null
    },
    {
      "displayName": "flange",
      "selectedName": "Sand / Metallic",
      "selectedColor": null,
      "colorHex": null,
      "finishName": null
    },
    {
      "displayName": "hardware",
      "selectedName": "Moss Green / Gloss",
      "selectedColor": null,
      "colorHex": null,
      "finishName": null
    },
    {
      "displayName": "lip",
      "selectedName": "Gold / Brushed",
      "selectedColor": null,
      "colorHex": null,
      "finishName": null
    },
    {
      "displayName": "lugs",
      "selectedName": "Moss Green / Gloss",
      "selectedColor": null,
      "colorHex": null,
      "finishName": null
    }
  ],
  "wheelImage": "data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAAA+gAAAPoCAYA...",
  "brand": "Amani Forged",
  "model": "Adesso",
  "cap": "-",
  "size": null,
  "offset": "-",
  "boltPattern": "-",
  "configuratorURL": {
    "queryParams": "https://amani.autoviz.io/configurator/178078/10?...",
    "productSku": "adesso"
  },
  "timestamp": 1765173179215
}

Key Differences

Aspect	SDK v1 (Legacy)	SDK v2 (Current)
Structure	Flat `wheelDetails` array	Hierarchical `sub_parts` object
Part identification	`displayName` only	Full part metadata (`part_id`, `part_key`, `part_type_id`)
Customization format	Combined string (`"Sand / Metallic"`)	Structured object with `type`, `sheen`, `color`
Color data	Often null, combined in `selectedName`	Full color object with `name`, `hex`, `is_custom`, `type`
Image format	PNG (`data:image/png`)	WebP (`data:image/webp`) for smaller file size
Image field name	`wheelImage`	`data_url`
Share URL field	Not present	`share_url` at top level
Part variants	Not supported	Full `part_variant` object with id and display name
Mapped ID	Not present	`mapped_id` for brand internal SKU mapping

Migration Guide

Accessing part customizations:

// SDK v1 - Flat array lookup
const v1Face = wheelDetails.find(d => d.displayName === 'face');
const v1FaceFinish = v1Face?.selectedName; // "Sand / Metallic"

// SDK v2 - Hierarchical object access
const v2Face = sub_parts.center?.customizations?.face;
const v2FaceFinish = v2Face?.type;     // "metallic"
const v2FaceColor = v2Face?.color?.name; // "sand"
const v2FaceHex = v2Face?.color?.hex;    // "#cbbd93"

Accessing the rendered image:

// SDK v1
const image = configData.wheelImage;

// SDK v2
const image = configData.data_url;

Accessing product info:

// SDK v1
const brand = configData.brand;
const model = configData.model;

// SDK v2
const brand = configData.brand;
const model = configData.display_name;
const sku = configData.mapped_id; // Brand's internal identifier

SDK v1 Legacy Support

SDK v1 format is still supported for specific legacy integrations. The format is automatically selected based on the embed host domain.

Overview​

localStorage Persistence​

Data Structure​

Complete Example​

Field Reference​

Top-Level Fields​

Part Variant Object​

Sub-Parts Object​

Customizations Object​

Color Object​

Configurator URL Object​

Reading from localStorage​

Finish Type Reference​

Migration from SDK v1​

SDK v1 (Legacy) Format​

Key Differences​

Migration Guide​

SDK v1 Legacy Support​