Vocabulary
This page aim to explain some vocabulary and terms related to our API and SDK. Depending on your previous experience with CET Designer and/or Catalogues some parts will be familiar. If you want to more in-depth information regarding CET Designer or Catalogues we recommend you visit our help center.
AccessToken
See Token.
Additional Product
A Product can have sub products. They can either be permanently attached to their parent product, or part of a Product Configuration. When being part of a Product Configuration it will be loading depending on the Feature/Option it belongs to being selected or deselected.
An Additional Product can also be optional in itself. It will then be possible to select or deselect it without use of Feature/Option. Optional Additional Products are by default deselected at load.
Additional Products can be recursively defined, that is, an Additional Product can have Additional Products itself. However, loops are not valid.
API
Application Programming Interface, in our case a Web API which outlines how remote calls are made to our servers.
ApplicationAreas
For each Catalogue there can be a number of default Material Mappings. The name ApplicationAreas can be a bit misleading, as for the context of the Web Configurator it is only used for Material Mapping.
Babylon
Babylon.js is the WebGL based web 3D-engine used by us for displaying Models on the web. It is open source and you will find documentation on https://www.babylonjs.com/.
Catalogue
Vendor / PrdCat / PrdCatVersion / PriceList
A Catalogue is a collection of Products. The Products in the catalogues are viewed through a filter of Vendor, PriceList and PrdCatVersion. These parameters can affect what products are shown in the Catalogue and aspects of the Products such as their price. While Vendor and PriceList are parameters that can be user selected PrdCatVersion is set by the Catalogue administrator and exists to guarantee that the right version is loaded.
Catalogue API
The API from which data about Catalogues, Models and such is retrieved. Also used to issue SessionTokens when using Public AccessTokens.
We tend to use the terms API and Web API interchangeably, so when we talk about the API you know we most often talk about this API.
Catalogue Auth API
The API which handles authentication when using Private AccessTokens. This is a separate API from the Catalogue API.
This API has to be used to issue SessionTokens to access the Catalogue API when using Private AccessToken.
Catalogue Creator
The tool used to create Catalogues. It is an extension for CET Designer. Product page.
Catalogue Stretch
It is not uncommon for Products to be orderable in custom sizes. Like the width and depth of a table, or the height of legs. Catalogue Stretch allows content creators to create Products where one Model can be stretched, driven by how the end user configures the product (Product Configuration).
Catalogues
When we talk about Catalogues as a singular noun we talk about the database driven system which powers all of this.
When we talk about Catalogues as a plural noun we talk about a collection of Catalogues (like in this sentence).
CET Designer
CET Designer is the software solution for space planning and configuration of products in which Catalogues used to be exclusively used. In the context of the Web Configurator it can be helpful to know it exists.
CmSym
CmSym is the most recent Model format used by Configura. CmSym is build on to of the Dex-file-format. It can beside geometry also contain other data, such as Materials.
If you use babylon-view or babylon-view-react to view your Products the format is handled in the background. If you build your own viewer we strongly recommend you use our package web-core to read it.
Configura
This is us! The company behind this and more.
Enterprise
The highest level of grouping in the Catalogues system.
Exerciser
Allows you to loop through viewing a number of Products and Catalogues to test them. Used by the test-app.
Feature
Material
A Material defines the texture of a Model. Materials is what makes it possible to display your item in glorious leopard patterned fabric.
Material Mapping
Synonyms: Area to Materials, Material Application
What Materials are applied to what Model parts is controlled through a Tag-system . Parts of Models have tags, and tags are mapped to Materials on different levels. Least priority goes to Material Mappings defined on Catalogue-level, next goes Mappings defined on Product level and highest priority has Product Configuration where the most specific selection has highest priority.
The combination of Catalogue, Product and Product Configuration will generate a Material Mapping were each tag is mapped to a Material. If no Material can be found for a tag it will fall back to Materials embedded in the Model.
Using tags for other programming purposes than Material Mapping is probably possible, but nothing we support outright.
Tags have other names (or other names are closely enough related for them to be used interchangeably in the context of Material Mapping).
- AreaTag
- Area (in the API)
- Layers (from Model Lab)
- SurfaceId (from Catalogue Creator)
- SymTag (this is how the tags are stored in the model data)
Model
A Model contains geometry, with some added data. Models can and is often reused between Products. If you have multiple Products using the same base it would be appropriate to use the same Model in all of them. Due to browser caching this will also help performance in the user end.
What Materials should be applied where is outlined using tags in the Models. Models are hierarchical tree-structures. How they are organized is depending on what tool generated them.
MyConfigura
MyConfigura is a an administration web site for everything Configura.
AccessTokens are issued in MyConfigura. You can also browse your Stage Enabled content.
Option
Pointer Events
Babylon.js uses Pointer Events for mouse and touch interaction, which not all devices and browsers support. Specifically, Apple iOS 12 and earlier does not support it. You can use a Pointer Events polyfill to improve compatibility. Babylon recommends using PEP from jquery for this.
Portfolio
A Portfolio is a collection of Catalogues.
The ID of a Portfolio is for legacy reasons called a 'CID'. The ID of a Catalogue is in turn called 'prdCat'.
Private AccessToken
See Token.
Product
A Product is an item in a Catalogue. It consists of Models outlining the geometry, Materials defining the surface look, configuration (Product Configuration) selecting what Models and Materials will be used and Features outlining what Models and Materials can be chosen.
Product Configuration
A Product can be user configured. This is the core of what the Web Configurator is about – showing Products in 3D and letting the user select how the Product should be configured.
The configuration can affect both geometry and texture. There are really no limitations to how the configuration can affect the geometry or texture, but mostly Products works as you would expect them to. Like a chair, it’s likely you would be allowed to select the upholstery, paint color and maybe the back rest. You would expect to still see the same chair, but as previous stated, there are not technical limitations.
How a Product is configurable is defined by Features and Options. These words hold special meaning in the context of Catalogues.
A Feature is typically something like “Seat”, “Back color” or “Legs”. A Feature has Options, typically more than one. Depending on the Feature one Option may be selected (like in a dropdown menu), multiple Options can be selected (like checkboxes) or all Options are always selected (used as a grouping feature).
An Option is typically something like “Green”, Round seat” or “Polka dots with Zebra stripes”. An Option can in turn have Features. Thus, Features and Options define a tree.
Selecting or unselecting an Option has the following consequences:
- The sub-Features toggles availability depending on the Option’s selectedness.
What Models are used can change. Imagine changing the backrest of a chair, since the new one has a different shape a new Model must be used.
What Models are used cannot be determined client side. A Validate call must be made to the server which will respond with a new set of Models (or the same ones).
- Price and such meta-data can change. In the same manner as Models this is evaluated server side and the new data will be given in the response of a Validate call.
Material may change. Imagine the upholstery of your chair changing from corduroy to leopard.
What Materials will be used is evaluated client side, and so it’s in theory possible to apply a material change before doing the Validate call. However, before getting the reply from Validate you won’t know if the configuration you requested is legal.
This description does not describe the inner workings of how Features, Options, what is selected and the API-calls work. We recommend you use our CfgProduct-class as an intermediate when working with Product Selection. This in turn uses the CfgProductSelection-class which exposes the tree with selections in a way which is closer to how you would present it, compared to the inner representation.
Public AccessToken
See Token.
React
React is our preferred front-end framework. It is widely used and well documented. You will find documentation on https://reactjs.org/ .
SDK
Software Development Kit. This is the code we have written for you. It can be used as a reference for how to do your own implementation towards the API, or its components can be used to greatly reduce the amount of code you need to write yourself. We recommend you use as much of the SDK as possible. Not only does it simplify the integration process, it also helps to guarantee that the API is access in the manner we intended it to.
SessionToken
See Token.
Stage
Stage is the name of Configura's Web Configurator solution.
Stage Embedded
Stage Embedded is what makes it possible to embed Stage on the web by simply inserting a short snippet of code. It works much the same as when embedding a Tweet or a YouTube-video.
Stage Embedded is more limited in what can be done and customized compared to a normal, full, integration but can be very useful when the full power of Stage is not needed.
Stretch
See Catalogue Stretch.
Sync Group
Sync Groups is a functionality in Catalogues where Features are made to try to stay in sync with each other. It is sort of a layer on top off the normal handling of selecting Options on Features and it is applied in a "best effort"-manner. Two Features belonging to the same Sync Group should be thought of as an intent for them to stay in sync. However, there is no hard connection involved. The Features can have different or partially overlapping domains (what Options can be selected) so there is no guarantee that they can always stay in sync. It's up to the Catalogue creator to build the Catalogue so that his or her intention is met.
Tag
Synonyms: Area
See Material Mapping.
Three
- Legacy - three.js is the WebGL based web 3D-engine that used to be used by us for displaying Models on the web. We have migrated to Babylon.
Token
Tokens are keys used to access resources provided by our API.
All tokens start with the Token ID. The TokenID begins with AT or ST denoting AccessToken or SessionToken, followed by the Amazon Region in which it was issued, followed by a string of random characters. The Token ID identifies the token in question and can be used to statistics and similar.
Most tokens also contain a Token Secret which is another group of random characters appended to the Token ID with a period to form the complete token.
The tokens are divided into two groups: SessionTokens and AccessTokens.
Session Tokens
Used by clients, often a user in a web browser to access our Catalogue API to retrieve catalogue data. They have a limited lifetime, and you are expected to handle the issuing of these to your end users.
Access Tokens
Used for authenticating your company and issue SessionTokens. Access tokens are either private or public and it is very important to understand the difference between them.
Private Access Tokens
Used by your backend server to issue new SessionTokens from our Catalogue Auth API.
Treat you Private Access Tokens (containing the Token Secret) like you would treat important passwords. Only use them inside your backend server and never use, expose, or send them to the client side!
Public Access Tokens
Used on the client side to issue new SessionTokens from our Catalogue API.
Easier to use compared to Private AccessTokens but also less secure. Since you are allowed to use these to the client side, it is possible for third parties to gain access to them. To make the usage of these tokens more secure it is possible to specify which domains are allowed to use a token. This is not totally secure, but it makes misuse of Public AccessTokens by third parties more difficult.
Token ID
See Token.
Token Secret
See Token.
Underscore
An underscore (_) when used in our SDK usually denoted one of the following:
- An unused function parameter kept around to make it easier to understand what parameters could be used in the function.
- Something semi-private. A function or a class or a field that we can not for technical reasons mark as private, but is not considered part of the public SDK. Try not to use these unless you have to. If you have any doubt whether or not you need to use one of these, please ask us.
Web Configurator
By this we mean either...
Our effort to help you to access and show content from Catalogues in apps and on the web. Welcome!
...or
A complete implementation allowing a user to show Products in 3D and configure them. This implementation could be using all our helpful tidbits from the SDK, or it could be scratch built down to the level of only using the API-calls (though we doubt we will see many of those).
WebAssembly
Synonyms: WASM
Until recently all code run in the web browser had to have been written in JavaScript, or transpiled into JavaScript from some other language. WebAssembly is a binary instruction format that can run in the web browser. We use it because of its great performance and it allowing us to programming in a language of our choice (Rust). It is also supported in all major modern browsers.
For the most part you will not notice parts of the code being WebAssembly, but as it might have impact on what platforms the code run on, we wanted to make you aware.