HTML Snippet Integration

With the HTML snippet you embed a configurator in any website – WordPress, TYPO3, Joomla, Jimdo or hand-built HTML. You need neither a shop plugin nor a developer: a <script> tag and a <div> with a few attributes are enough. The snippet always loads the V3 frontend engine.

When the HTML snippet fits

The HTML snippet is a good fit if you

• want to show the configurator on a regular web page, for example as a quote or inquiry tool,
• use a CMS without a shop,
• complete the inquiry with the action button – as an email, a PDF or to your own URL.

For Magento 2, Shopware 6 and Shopify there are ready-made plugins. They add price and configuration to the cart – the snippet alone can't do that. See Install Magento Plugin, Install Shopware Plugin and Installing the Shopify Plugin.

Step 1: Generate a token

1. In the admin, open Settings and there the Integrations tab.
2. Find the HTML5 (V3) card.
3. Click Generate. You get a token and below it the V3 JavaScript snippet with your customer ID and your token.
4. Copy the snippet with Copy.

The card has no switch – as soon as a token exists, the snippet works.

Rotate creates a new token and immediately invalidates all previous ones. After that the configurator no longer loads on any page until you've inserted the new snippet there.

Step 2: Allow the domain

Under Settings → Domains, enter the domains on which the configurator may run – without https://, e.g. www.mysite.com. An entered domain also covers its subdomains. Changes take effect after a few minutes. More on this in Global Settings.

This is not a formality: your token is in your page's source code and therefore readable by anyone. It's protected by this list. On a domain that's not listed, the configurator shows "Component could not be loaded (HTTP 401)" and below it Requesting host not authorized. If you test on a staging domain, enter that one too.

Step 3: Find the component ID

The ID is shown next to each component in the component overview, e.g. ID 10722. If it says ID —, the component hasn't been published yet. Publish it first – the snippet always shows the most recently published state.

Step 4: Insert the snippet

In the copied snippet, replace YOUR_TEMPLATE_ID with the ID of the component:

<script src="https://cloud.configento.app/configento-v3/configento.js" defer></script>

<div
    data-configento
    data-component-id="10722"
    data-configento-customer="YOUR-CUSTOMER-ID"
    data-configento-token="YOUR-TOKEN"
    data-configento-cloud-base-url="cloud.configento.app"
    data-configento-tax-rate="19"
    data-configento-locale="en_GB"
></div>

How it works: on load, the script looks for every element with the data-configento attribute and builds a configurator there. It reads everything else from the data-configento-* attributes of the same element.

Insert the snippet where your CMS allows custom HTML – usually a dedicated HTML block or HTML element. Many CMSs strip <script> tags from normal text blocks, so don't use the rich-text editor.

The <script> tag goes on the page only once, even if there are several configurators on it.

Step 5: Test

Open the page in the browser. The configurator appears with all characteristics. Without further attributes, the snippet shows no price, no summary and no title – see the next section. If something doesn't work, see Troubleshooting.

Placing price, summary and product image

On a web page, price and summary usually belong in a specific place in the layout, e.g. next to the product heading. That's why the snippet only shows them where you tell it to. You create your own elements and point to them with a CSS selector:

<div id="my-image"></div>
<h1>My product</h1>
<div id="my-price"></div>
<div id="my-summary"></div>

<div
    data-configento
    data-component-id="10722"
    data-configento-customer="YOUR-CUSTOMER-ID"
    data-configento-token="YOUR-TOKEN"
    data-configento-cloud-base-url="cloud.configento.app"
    data-configento-tax-rate="19"
    data-configento-locale="en_GB"
    data-configento-price-mount="#my-price"
    data-configento-summary-mount="#my-summary"
    data-configento-combined-image-mount="#my-image"
></div>

• Price (price-mount): total price with tax note. Errors and warnings from your rules also appear below it.
• Summary (summary-mount): the selected characteristics and values. In its own place it starts expanded; with data-configento-summary-open="false" it starts collapsed.
• Product image (combined-image-mount): the combined product image. Without this attribute it appears inside the configurator – the selector only moves it.

Everything updates live with every selection. The target element must already be in the HTML when the page loads; an element that's only created later by JavaScript isn't found by the configurator. If the selector finds no element, that display is left out – the configurator itself still works.

Showing everything inside the configurator

If you simply want title, price and summary inside the configurator itself, as in the preview in the admin, set:

data-configento-embed-mode="admin-preview"

Then the component title, price bar and summary appear inside the configurator. price-mount and summary-mount work in addition and move the respective element to your place.

Languages

data-configento-locale sets the language – for the component's texts and for the configurator's labels ("Total", "Please choose"). If a text is missing in this language, the configurator uses the same language of another region (e.g. en_US instead of en_GB), otherwise another available translation.

Language selection first

If your component exists in several languages, the configurator can ask the visitor first. It then shows a tile with flag and language name for each language and starts in that language after the click.

data-configento-language-select

The component's languages are offered. For a particular site, you narrow them down:

data-configento-language-select
data-configento-languages="de_DE, en_GB"

To show a text above the flags:

data-configento-language-select-title="Choose your language"

The text appears exactly as you write it. The visitor hasn't picked a language yet, so if you serve several markets, write it in all of them, e.g. "Choose your language / Sprache wählen".

To let the visitor change the language later, call showLanguageSelect(), for example from a button:

<button type="button" onclick="Configento.first().showLanguageSelect()">Change language</button>

The flags appear again; the current selection in the configurator is kept. More in JavaScript API (V3).

Good to know:

• With only one language, no selection appears.
• The choice applies for the browser session: anyone who reloads the page or comes back isn't asked again.
• The visitor's choice takes precedence over data-configento-locale.

To try it out: demo "Multilingualism".

All attributes

Basics

Attribute	Meaning
data-configento	Marks the element as the place for a configurator. No value.
data-component-id	ID of the component
data-configento-customer	Your customer ID – it's in the snippet
data-configento-token	Your token from the HTML5 (V3) card
data-configento-cloud-base-url	cloud.configento.app – keep it unchanged
data-configento-tax-rate	Tax rate the configurator converts prices to, e.g. 19. If it matches your component's tax rate, prices stay unchanged; 0 shows net prices. Without the attribute, the configurator shows prices exactly as they are entered in the component.
data-configento-locale	Language, e.g. de_DE or en_GB

Display

Attribute	Meaning
data-configento-price-mount	CSS selector for the price. Without this attribute, no price.
data-configento-summary-mount	CSS selector for the summary. Without this attribute, no summary.
data-configento-summary-open	Summary initially expanded (true) or collapsed (false)
data-configento-combined-image-mount	CSS selector for the combined product image
data-configento-embed-mode	admin-preview shows title, price and summary inside the configurator
data-configento-min-height	Reserves the height while loading, e.g. 640px, so the page doesn't jump. With data-configento-min-height-keep it stays afterwards too.
data-configento-wizard-nav	Navigation in the wizard: full, buttons or none – see Controlling the wizard and groups

Languages

Attribute	Meaning
data-configento-language-select	Language selection before the configurator. No value.
data-configento-language-select-title	Text above the flags of the language selection
data-configento-languages	Offered languages, separated by commas
data-configento-content-locale	Language only for the component's texts, if it should differ from the labels. Rarely needed.

Rarely needed

Attribute	Meaning
data-configento-config	All settings as JSON (see below)
data-configento-currency	Currency code, e.g. EUR, if it should differ from the component
data-configento-component-json	The component directly in the page instead of fetching it on load – see Loading faster

Further attributes such as data-configento-token-endpoint and data-configento-asset-base-url are set by the shop plugins. Leave them out in the HTML snippet. All attributes with their JSON names are listed in the JavaScript API reference.

For yes/no attributes, the attribute without a value counts as "yes". true/false, 1/0 and yes/no are also allowed.

Several configurators on one page

You can place as many data-configento elements on a page as you like. Each loads its own component and calculates on its own. Include the script only once.

Give each element its own id and point price-mount and the other selectors to separate targets. You also address the configurators via JavaScript through the id.

Settings as JSON

If many attributes are awkward in your CMS, combine them in one attribute:

<div data-configento data-configento-config='{
    "componentId": "10722",
    "customer": "YOUR-CUSTOMER-ID",
    "token": "YOUR-TOKEN",
    "cloudBaseUrl": "cloud.configento.app",
    "taxRate": "19",
    "uiLocale": "en_GB",
    "priceMount": "#my-price"
}'></div>

The names in the JSON: componentId, customer, token, cloudBaseUrl, taxRate, uiLocale, contentLocale, currency, priceMount, summaryMount, summaryOpen, combinedImageMount, embedMode, languageSelect, languageSelectTitle, languages (as a list, e.g. ["de_DE", "en_GB"]), minHeight, minHeightKeep, wizardNav, productAttributes and component. If a setting is in the JSON and also a separate attribute, the JSON wins.

Mind the single quotes on the outside so the double quotes in the JSON are preserved.

JavaScript API

For your own logic on the page – such as your own inquiry button, a form or the price in your purchase bar – the configurator provides window.Configento:

<script>
  window.addEventListener('DOMContentLoaded', function () {
    Configento.ready.then(function () {
      var configurator = Configento.first();

      configurator.on('price', function (p) {
        console.log('New total price:', p.total, p.currency);
      });
    });
  });
</script>

All methods and events, saving and loading configurations, and switching from Legacy code are described in JavaScript API (V3).

The classic snippet

Accounts with the classic cloud also see the HTML5 card under Integrations. It has a switch, its own security token and, when switched on, a JavaScript snippet (with _configentoSettings and html5.js) and an iFrame snippet. Both load the Legacy frontend engine.

Existing embeds with the classic snippet keep working unchanged. For new embeds, use the V3 snippet: only it offers the language selection, your own places for price, summary and image, the JavaScript API and V3 features such as the captcha.

To switch, replace the old snippet completely with the new one – the two can't be mixed. The customer ID stays the same, the token is a different one: it comes from the HTML5 (V3) card. What changes when you switch engines is described in Frontend Engine: Legacy or V3. If you have your own JavaScript code for the classic snippet, see Switching from Legacy.

Troubleshooting

What you see	Cause and solution
Nothing at all, no box	The CMS removed the <script> tag. Use an HTML block instead of a text block.
"Component could not be loaded (HTTP 401)" with Requesting host not authorized	The domain is missing under Settings → Domains – enter staging domains too.
"Component could not be loaded (HTTP 401)" with Token invalid	The token is wrong or was replaced with Rotate. Copy the snippet again from the HTML5 (V3) card.
"Component could not be loaded (HTTP 404)"	YOUR_TEMPLATE_ID not replaced, wrong ID, or component not published yet
Configurator is there, but no price	data-configento-price-mount is missing, or the selector finds no element. Alternatively data-configento-embed-mode="admin-preview".
Prices too low, like net	data-configento-tax-rate is set to 0 or to a lower tax rate than in the component
Changes from the admin are missing	The component hasn't been published since the change.
Language selection doesn't appear	The component has only one language, or the visitor already chose in this session.
A characteristic shows "Unknown characteristic type"	The component uses a feature that only exists in Legacy – see Frontend Engine: Legacy or V3.

The browser console gives further hints: the configurator's messages start with [Configento].

Next steps

• The Action Button
• Frontend Engine: Legacy or V3
• Global Settings
• Create Your First Component