Embedding & Whitelist
  • 23 May 2024
  • 3 Minutes to read
  • Contributors
  • Dark
    Light

Embedding & Whitelist

  • Dark
    Light

Article summary

Embedding

To embed a Configurator in a website, only two HTML tags (<script>& <iframe>) are required, example:

<script src="https://portal.combeenation.com/plugin/COMPANY/CONFIGURATOR"></script>
<iframe class="cbn-embedded-configurator" frameborder="0" data-cfgrurl="https://portal.combeenation.com/Cfgr/COMPANY/CONFIGURATOR">
</iframe>

The <script> tag (the plugin) is required to achieve communication between the parent page and the configurator. The script tag has to be included every time and should be embedded in the <head>-section of the website.

<iframe> is a HTML 5 element which basically just displays another website (e.g. Combeenation configurator) in the current website (e.g. your website). Place this element wherever the configurator should be visible on the website.

Embed Snippet

Combeenation platform provides a ready-to-go embed snippet for your configurator under Dashboard > Embedding. Basically, you just need to paste the code on the desired place on your website and you're good to go.

If you are using a CMS (e.g. WordPress, Drupal, ...) there is most likely some kind of HTML editor, which allows you to add the embed code to the page. If you are unsure where to put the code or don't have access to your code please contact your web administrator.

Best practice - Step by Step

To provide the best embedding experience, please follow the according steps.

Step 1

Make sure that the correct media queries are used within the configurator. Otherwise, the embedded configurator will scale poorly and incorrectly.

min-width, max width, min-height or max-height

min-device-width, max-device-width, min-device-height or max-device-height

@media only screen 
and (min-width : 123px)
 and (max-width : 456px) { 
       ... 
}

Step 2

Embedding the <script> in the <head> section of the website:

<script src="https://portal.combeenation.com/plugin/COMPANY/CONFIGURATOR"></script>

And the <iframe> in the <body> wherever the configurator should later be displayed.

<iframe class="cbn-embedded-configurator" frameborder="0"
data-cfgrurl="https://portal.combeenation.com/Cfgr/COMPANY/CONFIGURATOR">
</iframe>

Use correct values

The values for COMPANY and CONFIGURATOR need to be exchanged to those of your configurator.

Step 3

Next step would be the customizing the <iframe> element. It depends on how the configurator is embedded into the website.

Directly into the website:

.cbn-embedded-configurator { 
        width: 100vw; 
        height: 100vh; 
}

Standalone page:

.cbn-embedded-configurator { 
         width: 100vw; 
         height: calc(100vh -NAVHEIGHT); 
}

The <iframe> element provides several attributes which customize the behavior or appearance:

  • class="cbn-embedded-configurator"... This CSS class is required, because the plugin uses it to identify configurator

  • frameborder="0" (optional) ... is used to specify whether to display the border around the content

  • allow="clipboard-write" (optional) … to allow copy-paste from the <iframe> page

  • allow="fullscreen" (optional) … allows the configurator to go fullscreen

Step 4

Make sure to test the finished embedded configurator on desktop, tablet and smartphone devices.
Height of the iframe can vary depending on the used web browser.

Whitelisted Domains

A Combeenation configurator can be embedded into a limited or unlimited number of websites, depending on your subscription. You can choose these so-called "whitelisted" domains on which your configurator may be used.

Attempting to use the configurator on any other website will result in an error. The domain restriction can be circumvented by crafty users that temper with their browser settings (or use custom browsers), but it will be effective for everyday users. This makes it unappealing for scammers or other malign parties to try and mislead users by embedding your configurator, as it won't work for the broad majority of users.

You can configure the whitelisted domains for your configurator under Dashboard > Embedding > Whitelist domains.

Watch out!

If your configurator is already embedded into several sites and you haven't set any whitelisted domains yet, then once you add the first domain, the configurator will be blocked on all other sites!

If you are in this situation, prepare a list of all domains beforehand and then enter them all at once to avoid any downtimes.

Configurator URLs

This section explains the different URLs and how they can be used to open a configurator.
Each URL starts with https://portal.combeenation.com/Cfgr and can end with one of the following:

/{YourCompany}/{YourConfigurator} - the default configurator URL which will start a new configuration based on the default preset
/{YourCompany}/{YourConfigurator}/{PresetName} - configurator URL which will start a new configuration based on the given preset
/{YourCompany}/{YourConfigurator}/{ConfigurationId}/copy - URL which starts a new configuration based on a given configuration
/{YourCompany}/{YourConfigurator}/{ConfigurationId}/edit/{ConfigurationAuthToken} - URL which lets the user edit an existing configuration

Explanation of the substitutes (terms in curly braces {})

{YourCompany} - the reference name for your company on the platform
{YourConfigurator} - the reference name for your configurator
{PresetName} - the id or the name of your preset (see preset view in configurator editor, where you can also set the default preset for your configurator)
{ConfigurationId} - is a unique number which identifies a configuration, will be generated for each new configuration.
{ConfigurationAuthToken} - text which is needed to edit an existing configuration, will be generated for each new configuration.


Was this article helpful?

What's Next