1.4 - Application Distribution

To be able to use the Product Configurator, you have to create an Application Distribution.

Domains

After creating the Application Distribution, do not forget to configure the associated domains. 🔗

tip

You can find a full sample here: Application Distribution Sample 🔗

Creation

You can follow this documentation to create one: How to create and Application Distribution 🔗

You will have to choose:

Field	Value
Associated Application	Product Configurator
Permission	Anonymous
Catalog	Choose at least one catalog here to have access to some products
Parameters	This is mandatory, see more information below. 🔗

Parameters

The parameters are filled using the JSON format.

Supported settings

For...	See...
Language, Units and Currency	`locales`, `currencies`
Search filters	`search`
Pricing	`pricing`
Integration	`integration`

Top structure

The application distribution settings object is defined with the following attributes:

Attribute	Type	Description
`currencies`	array of objects	A list of supported currencies in the application distribution
`integration`	object	Web component integration parameters, when set from the App Distrib
`locales`	array of objects	A list of supported locales in the application distribution
`pricing`	object	Application distribution settings related to the pricing
`search`	object	The data related to the search inside the application.

The only mandatory attributes are: locales

Currencies

Attribute name	Status	Type	Default value
`currencies`	Optional	array of currency objects	`[]`

This parameter contains a list of specific currency configurations for the Application Distribution. Each object in this array is used to configure how a particular currency is configured for its display in the application.

When the application starts, it determines which currency to use ( see data-pricing -> currencyCode integration parameters 🔗. If it is in this list of currencies, it uses the associated object to configure the currency display. If the currency is not in the currencies list, it falls back on the locale-currency configuration ( see GET /applications/{id}/currencylocales/{locale} 🔗).

A currency object is defined as follow:

Attribute	Type	Mandatory	Description
`currencyCode`	string	YES	A 3 letters string following ISO 4217 🔗
`currencyName`	string	YES	The currency name
`numberSystem`	string	YES	"latin" or "arab". Defines which alphabet to use to display the digits
`currencySymbol`	string	YES	The symbol to display for the currency
`currencySignRighthand`	boolean	YES	Defines if the currency symbol should be on the right side of the price number. `true` to display the symbol on the right side
`currencySpacing`	boolean	YES	Defines if there should be a space between the price number and the currency symbol. `true` to display a spacing
`decimalSeparator`	string	YES	The separator string to separate the decimal digits of the price
`thousandSeparator`	string	YES	The separator string to separate the thousand groups
`noDecimalString`	string	YES	The string to display when there is no decimal digits

Example 1 – Array of two currencies

{
    "currencies": [
        {
            "currencyCode": "GBP",
            "currencyName": "British Pound",
            "numberSystem": "latin",
            "currencySymbol": "£",
            "currencySignRighthand": false,
            "currencySpacing": false,
            "decimalSeparator": ".",
            "thousandSeparator": ",",
            "noDecimalString": ""
        },
        {
            "currencyCode": "EUR",
            "currencyName": "euro",
            "numberSystem": "latin",
            "currencySymbol": "€",
            "currencySignRighthand": true,
            "currencySpacing": true,
            "decimalSeparator": ",",
            "thousandSeparator": " ",
            "noDecimalString": ""
        }
    ]
}

Integration

Attribute name	Status	Type	Default value
`integration`	Optional	Object	`{}`

This parameter let the Application Distribution modify the integration values of the web component. It has two usages:

When the Product Configurator is launched through the planner, it's the only way to set integration values.
When the Product Configurator is integrated on another website, this allows setting and changing defaults values without any modification on the customer side.

See the dedicated page for the configuration of the Product Configurator 🔗.

Example 1 – Modification of the startup camera

{
  "integration": {
    "camera": {
      "defaultHorizontalAngle": "45",
      "startupAnimationDuration": "1500"
    }
  }
}

Locales

Attribute name	Status	Type	Default value
`locales`	Mandatory	array of locale objects	`[]`

This parameter contains the list of supported locales for the Application Distribution. It must contain at least one element.

A locale object is defined as follows:

Attribute	Type	Mandatory	Description
`isDefault`	boolean	NO	If `true`, tells the application to use this locale by default. It is possible to launch the configurator with a specific locale. 🔗
`name`	string	YES	A combination of a mandatory and an optional element joined in a string and separated by a "-" (dash). - MANDATORY: 2-letter code of a language, following ISO 639-1 🔗. - OPTIONAL: 2-letter code of a region / country, following ISO 3166-1 🔗. Examples: "da-DK" for "Danish-Danemark" or "fr-FR" for "French-France" or "PT-pt" for "Poruguese-Portugal".
`fallback`	string	NO	Used for translations only. If a translation key is not found for the given locale, the translation system falls back to this locale instead. If not specified, falls back to English.
`unitSystem`	string	YES	Defines which unit system is used in the application. Can be `metrics` or `imperial`
`lengthUnit`	string	YES	Defines the base unit for length in the application. Can be `millimeter`, `centimeter`, `decimeter` or `meter` (for unitSystem = metrics) and `inch`, `foot` or `yard` (for uniSystem = imperial)
`lengthPrecision`	integer	YES if uniSystem is metrics	The various lengths displayed in the application will be displayed with lengthPrecision decimal digits
`lengthFractionPrecision`	integer	YES if uniSystem is imperial	Minimal fraction of `lengthUnit`. Valid values are: 8, 16 or 32

Example 1 – Array of three locales in metrics

{
    "locales":
    [
        {
            "name": "fr-BE",
            "unitSystem": "metrics",
            "lengthUnit": "millimeter",
            "lengthPrecision": 0,
            "fallback": "en"
        },
        {
            "name": "nl-BE",
            "unitSystem": "metrics",
            "lengthUnit": "millimeter",
            "lengthPrecision": 0,
            "fallback": "en"
        },
        {
            "name": "de-DE",
            "unitSystem": "metrics",
            "lengthUnit": "millimeter",
            "lengthPrecision": 0,
            "fallback": "en"
        }
    ]
}

Example 2 – Array of two locales in imperial

{
    "locales":
    [
        {
            "name": "en-US",
            "unitSystem": "imperial",
            "lengthUnit": "foot",
            "lengthPrecision": 0,
            "lengthFractionPrecision": 16,
            "fallback": "en"
        },
        {
            "name": "es-US",
            "unitSystem": "imperial",
            "lengthUnit": "foot",
            "lengthPrecision": 0,
            "lengthFractionPrecision": 16,
            "fallback": "en"
        }
    ]
}

Pricing

Attribute name	Status	Type	Default value
`pricing`	Optional	Object with pricing information	`{}`

The pricing attribute groups settings related to pricing configuration. They are described after the example.

Example 1 – Pricing object

{
    "pricing": {
      "externalPrice": false,
      "hide": false,      
      "marketZone": "zone_1",      
      "priceTopAssembly": false
    }
}

`externalPrice`

Status	Type	Default value
Optional	boolean	`false`

Set to true if you want to use an external module to compute the Product Configurator price. By choosing this option, after each BOM computation, the configurator sends it via a message 🔗 and waits for a reply that must contain the Product Configurator price to display in the UI.

`hide`

Status	Type	Default value
Optional	boolean	`false`

Defines whether the total price is displayed or not in the application.

`marketZone`

Status	Type	Default value
Optional	string	``

Defines an optional market zone to use when computing prices. The end user will see the prices associated with the given market zone.

`priceTopAssembly`

Status	Type	Default value
Optional	boolean	`false`

Indicates whether the assembly product prices should include the price of the top assembly or not. This only affects assembly products (i.e. BMA products); Single component products (i.e. BM3 products) are always priced with their own price.

Attribute name	Status	Type	Default value
`search`	Optional	Object	`{}`

This parameter contains the data necessary to configure the search in the application.

A search object is defined as follows:

Attribute	Type	Mandatory	Description
`filters`	array of filters 🔗	NO	The list of filters to use for product lists.

Filter

To declare a filter, you create an object that contains the following attributes:

Attribute	Type	Mandatory	Description
`key`	string	YES	The filter to display. It can be: `closed_tags_color`: filter by the color closed tag of a product. `closed_tags_material`: filter by the material closed tag of a product. `closed_tags_room`: filter by the room closed tag of a product. `closed_tags_style`: filter by the style closed tag of a product. `closed_tags_type`: filter by the type closed tag of a product. `[parameter_id]`: the id of any parameter you want to use as a filter.
`order`	string	NO	The define the sort order of the filter values. By default, the values are sorted in ascending order. It can be: `asc`: values will be sorted in ascending order. `desc`: values will be sorted in descending order.

Translations

The displayed name of the filter will be the name of the parameter itself when the key refers to a custom parameter. It will use the translation key of the parameter as it is defined on the products having this parameter in the list of possible values.

When the filter refers to a closed tag (one of the predefined filter keys), the translation is provided by default.

Example 1 – Configured search filters

{
  "search": {
    "filters": [
      {
        "key": "closed_tags_style",
        "order": "asc"
      },
      {
        "key": "closed_tags_material",
        "order": "desc"
      },
      {
        "key": "closed_tags_type"
      },
      {
        "key": "boolean_filter"
      }
    ]
  }
}

Domains

warning

You have to secure the Product Configurator with a domain whitelist. This is the list of websites allowed to access your data.

This is mandatory. Without this, some functionalities will not work as expected.

Domains to add

Mandatory: Add the domains of the Product Configurator itself:
- https://staging-productconfigurator.enterprise.by.me/
- https://productconfigurator.enterprise.by.me/
Mandatory: Add your own domains, where you will use the configurator. Add the production AND preproduction environments.
Optional: Add a local domain so we can debug your data in our development environment:
- http://localhost:9898/

Request scope

You can create the whitelist of domains at two levels:

Legal 🔗: this will be effective for all the applications of your legal.
- Be careful with this: if you use other products, you will need to add the domains they are used on.
Application Distribution 🔗: this will only affect this ApplicationDistribution.

warning

Don't forget to Log In using the top button before sending some requests.

Request data example

When configuring the domains for the Legal or the Application Distribution, you will need to send some data. Here is an example of the data to send.

The operator set to 3 is used to replace the existing configuration with the list in data.
The data array contains the full list of authorized domains.

{
  "operator": 3,
  "data": [
    "https://staging-productconfigurator.enterprise.by.me/",
    "https://productconfigurator.enterprise.by.me/",
    "http://localhost:9898/"
  ]
}

Creation​

Parameters​

Supported settings​

Top structure​

Currencies​

Integration​

Locales​

Pricing​

externalPrice​

hide​

marketZone​

priceTopAssembly​

Search Filters​

Filter​

Translations​

Domains​

Domains to add​

Request scope​

Request data example​

Creation

Parameters

Supported settings

Top structure

Currencies

Integration

Locales

Pricing

`externalPrice`

`hide`

`marketZone`

`priceTopAssembly`

Search Filters

Filter

Translations

Domains

Domains to add

Request scope

Request data example