Documentation

# Migration guide v2 to v3

For several years we collected the feedback from the market and incorporated it into the development of version 3 of the Roomle configurator. The new user interface is now fully mobile and desktop ready and is developed with the Roomle Web SDK.

The most noticeable change is of course the new user interface. It brings the user experience to a whole new level and also works frictionlessly on mobile. Furthermore, the simplistic design makes it easier to integrate the new user interface into your website or webshop and reduces the need for skinning. Therefore the skinning options were slimmed down a lot.

# New behaviour on small visual spaces

During our user tests, we noticed that it is important that the configurator is embedded in reasonable screen size because otherwise there is just too little space to provide a good user experience for your customers. We already recommended this in the old configurator but we saw that some of our clients had difficulties with it. Mostly this is due to the fact that the right size is difficult to determine. It depends on your content, the user interface, the device of the user, and many more factors. Therefore the Roomle configurator is doing this now for you. Basically those steps are happening:

  • if the space for the Roomle Configurator is too small it starts in view-only mode
  • in view-only mode your customer can still directly order the product or view it in 3D
  • when the customer wants to customize the product, the Roomle Configurator opens as an overlay over the whole page (we call it full-page mode).
  • depending on the size of the user's screen the Roomle Configurator will display the mobile interface or the desktop interface

This has some implications:

  • to create this overlay, the Roomle Configurator has to be in control of all the DOM elements which are needed to expand over the whole page. Therefore things like the footer are now within the iframe and not custom made by the website or webshop. This makes embedding the Roomle Configurator easier because you do not have to wire up all the events and callbacks to create user interface elements like the footer. On the other hand, this also means that old parts of the embedding need to be removed from your website or webshop and re-thought.
  • also it is important to note that there shouldn't be elements with a higher z-index as the Roomle Configurator because the correct z-indices are needed for the full-page mode.
  • there is a back button which closes the full-page mode. If you need to listen to the event when the user clicks the back button this is possible and described in the section react on button clicks in the docu.

With the new version, it is essential that you use the correct configurator id. You should get the configurator id from your Roomle contact person. This is important because of two reasons:

  • the configurator id is used for security checks
  • and it identifies your configurator with our backend, therefore you can now change the configurator settings in our backend and do not need to update the code of your website or webshop if you want to change things like colors, etc.

# Legacy browsers

Since the support of IE11 is fading out and also big companies like LinkedIn (which is owned by Microsoft) stop supporting IE11 (for more information read their statement (opens new window)) we also decided to drop support for legacy browsers. This enabled us to create a more performant and interactive experience for users with modern browsers. Please bear in mind that you should create a fallback for legacy browsers. The Roomle Configurator can not provide a good fallback because it totally depends on your user journey and the structure of your website or webshop. Therefore we suggest two user journeys. One for legacy browsers and one for modern browsers which are able to fully embrace the Roomle Configurator.

# Coding

If you migrate from v2 please make sure you understood the old docu and the old code. The docu for v2 can be found on Github (opens new window).

Since it's a complete overhaul of the old configurator much of the "glue" code needs to be re-written but those things are basically only the entry points to your code. For example: if you calculate the prices based on the part-list you now attach your calculation to instance.ui.callbacks.onPartListUpdate instead of RoomleConfigurator.addChangeListener. The interface of the function stays the same and you do not need to adjust your implementation. So the biggest migration steps will be to attach your code to the new callbacks. Let's see some code for the above-metioned example:

# Example part list and price calculation

# Old

const calculatePrice = (parts /* your price calculation */) =>
  RoomleConfigurator.addChangeListener(calculatePrice);
await RoomleConfigurator.init(/* for details about the create method see the old docu */);

# New

const calculatePrice = (parts) => /* your price calculation, same code as with the old version */
const instance = await RoomleConfiguratorApi.createConfigurator(/* for details about the create method see the new docu */);
instance.ui.callbacks.onPartListUpdate = calculatePrice;

# New instantiation

Another thing that is new is the way the configurator is instantiated. Since we were able to drop IE11 support we are now able to create multiple instances of the Roomle Configurator on a site of a website. Therefore you do not need to rely on a global object and you can just import the Roomle Embedding API as every other ES6 module.

Furthermore, we provide now two convenient ways to load a product into the configurator. Either you instantiate the Roomle Configurator without a product and use loadObject later or you pass in an ID as init-option. Both ways have their pros and cons. Let's review them quickly.

When you have a detail-page of a product in your webshop or website it makes sense to pass the ID as init-option (because you know which product your customer wants to see). This makes it possible that everything is loaded in parallel, the code of the configurator, and the content of your product. This speeds up the loading process. On the other hand, it makes no sense if you load some product when you do not know which product your customer wants to see in the configurator. This could be the case if the Roomle Configurator is opened on a list-view page where several products are listed. Here it makes sense to only instantiate the configurator. This only loads the code of the configurator. When the user then selects a product you can use the loadObject method to load this specific product.

# Old

// the ID of your configurator
const configuratorId = 'demoConfigurator';
// a HTML id of a dom object
const domId = 'configurator-container';
// object to load
const objectToLoadId =
  'usm:frame:BB3BB3E7951BC15109B1FF86D78C95DE3FB46E9F78714C46FFA2DE91866A2C2B';
// hardcoded options which are passed to the configurator
const options = {
  /* lots of options hardcoded into your website or webshop */
};

// Only one instance is possible because there is only one object at the global scope
// No way to only load the configurator without content (content can not be loaded at a later point)
await RoomleConfigurator.init(configuratorId, domId, objectToLoadId, options);

# New

// the ID of your configurator
const configuratorId = 'demoConfigurator';
// just pass in a real DOM element so you can decided how this DOM element is discovered
const domElement1 = document.getElementById('configurator-container-1');
// use a second DOM element to instantiate a second configurator, just because you can now ;-)
const domElement2 = document.getElementById('configurator-container-2');
// object to load
const objectToLoadId =
  'usm:frame:BB3BB3E7951BC15109B1FF86D78C95DE3FB46E9F78714C46FFA2DE91866A2C2B';
// do not hardcode any options only if you want to override options from the server, e.g.: locale, or loading ID
const overrideServerOptions = {
  /*
   * -) use this if you want to override server options, e.g.: locale or language if it's based on the user
   * settings
   *
   * -) also you can specify an id here to instantly load the product so you do not have to call instance.ui.loadObject, this mimics the loading behaviour of the v2 for that specify the following keys in the options hash:
   *     "id": "some-id",
   */
};

// instantiate the first configurator and directly load the product
const configurator1 = await RoomleConfiguratorApi.createConfigurator(
  configuratorId,
  domElement1,
  { id: objectToLoadId, ...overrideServerOptions },
);
// instantiate the second configurator, because you can now :-) and wait with the load of the object
// until the user clicks on a specific product
const configurator2 = await RoomleConfiguratorApi.createConfigurator(
  configuratorId,
  domElement2,
  overrideServerOptions,
);
// load the object into the second configurator when the user clicks on a specific button
document
  .getElementById('button-to-load-product-x')
  .addEventListener('click', () => {
    configurator2.ui.loadObject(objectToLoadId);
  });

For instantiation, you need to provide a configurator id (please ask your Roomle contact person about the correct id). This id is used to fetch all the init data from the backend. The old version handed them to the configurator as JSON from the embedding website or webshop. This had the big disadvantage that you always needed to change the code of the embedding website or webshop when you wanted to change only the settings of the Roomle Configurator. Since the settings are now fetched from the backend based on the configurator id you can change them without a need to adjust code.

# Note on IDs

The new UI will just infer if you want to load a configuration or an item. This is based on the number of : in the ID. If you have two : in the ID it is a configuration and otherwise it is an item. For very old projects and very old IDs this logic is not always true. If you encounter 404 network errors in your browsers dev tools this is probably due to old legacy IDs. This should only happen in very rare cases since almost all of our customers are on the new logic but if you still have those old IDs you can give the Roomle Configurator the information it needs by passing in the option isItem: true/false.

# Note on startTag

The startTag feature helped our customers to create quick landing pages of a set of products. But it left a lot of wishes open and almost every customer had special needs for those landing pages. This is perfectly valid because those landing pages need to be optimized for your webshop and integrated into the SEO concept. Since this is not possible to do within an iframe we decided to drop this feature. Also because the new UI makes it very easy to integrate the configurator on a product list view landing page. Therefore it is now quick and uncomplicated to create a landing page customized to your special needs and load products into the configurator accordingly.

# Price service

Very old setups could need the overrideTenant parameter. All the new setups will automatically detect the correct setting. The overrideTenant parameter is a security check so that no sensitive data is leaked. Depending on your account settings this option is needed or not. If you see the error message prices are empty on the Chrome Dev Tools console it is likely that you need to set the overrideTenant parameter. Since you rely on a deprecated parameter please speak to your customer success manager how to get rid of this option.

# Technical considerations

We changed the entry points to stay more aligned with the Roomle Web SDK. This creates a better-unified experience across all the Roomle tools and products and enables you to change between those tools or use different tools in different contexts without the need to completely learn everything again.

To make the embedding easier we slimmed down the API surface of the configurator. The smaller API surface eases the learning curve and helps to scaffold the project faster. We paid close attention to the needs of our customers and now we can provide an API which is focused on the essential things and has all the functionality which is needed to create a good user journey on your website or webshop. Many best practices and "recipes" are described in the new docu. If there is something essential missing please speak to your Roomle contact person.

We especially simplified the skinning options because we think that the current user interface is very "neutral" and should fit with slight adjustments to most of the websites and webshops out there. If there is a strong demand for huge user interface adjustments and changes we can offer the Roomle Web SDK or forking of the UI repo. If this is really needed please speak with your Roomle contact person.

Because the user interface changed completely it's also a good time to rethink how the Roomle Configurator is embedded into your website or webshop. Therefore we recommend to read through the new docu and explore the new possibilities which the new configurator gives you. You can find the new docu here