Project Configurators

Presentation

Project configurators can be configured to provide your users a way to configure a specific part of their home, using a dedicated tool. Good examples would be a kitchen configurator, or a closet configurator.

Linking a project configurator to Home Retailers works a little bit like the external product configurators. First you have to register an external configurator, and then provide the list of your configurators to Home Retailers.

What configurators are available ?

3DVIA provides the following project configurators out of the box:

Project configurator	App ID	main URL	staging URL
Kitchen configurator	kitchenconfigurator (2)*	https://kitchenconfigurator.enterprise.by.me/LiteKitchen/index.html?distributionID={your_distrib_ID}	https://staging-kitchenconfigurator.enterprise.by.me/LiteKitchen/index.html?distributionID={your_distrib_ID}
Bathroom configurator	bathroomconfigurator (7)*	https://bathroomconfigurator.enterprise.by.me/BathroomConfigurator/index.html?distributionID={your_distrib_ID}	https://staging-bathroomconfigurator.enterprise.by.me/BathroomConfigurator/index.html?distributionID={your_distrib_ID}
Closet configurator	closetconfigurator (12)	https://closetconfigurator.enterprise.by.me/ConfiguratorIframe/index.html?distributionID={your_distrib_ID}	https://staging-closetconfigurator.enterprise.by.me/ConfiguratorIframe/index.html?distributionID={your_distrib_ID}

*the Kitchen Configurator app ID is the same than the full standalone Kitchen app (2) *the Bathroom Configurator app ID is the same than the full standalone Bathroom app (7)

You can also use an external project configurator as long as it respects the common interface that we put in place, see below.

Configuration

Declare a configurator

To declare a 3DVIA project configurator you first have to create a application-distribution for this configurator. If you use a project configurator provided by 3DVIA, use the associated app ID in the list above for your app-distribution.

To declare a configurator, use the dedicated web-service 🔗 and create a configurator by giving the following settings:

• id: the ID of your project configurator. Must be unique.
• name: the configurator name (not used in Home Retailers).
• description: the configurator description (not used in Home Retailers).
• url: the configurator main URL. For our out-of-the-box configurators, check the table above and make sure to include your created app-distribution ID.
• stagingUrl (optional): the configurator URL to use for the staging version of the Home Planner. For our out-of-the-box configurators, check the table above and make sure to include your created app-distribution ID.
• configuratorTypeID: this must be set to 2 to indicate a project configurator.

Other settings may be ignored.

Configure Home Retailers

Once your project configurators have been declared, you have to reference them in the Home Retailers app-distrib settings.

See the associated app-distrib settings documentation 🔗

You should then see a new "configurators" entrypoint in the application, that lets you launch your project configurators in full screen.

Use an external project configurator

Any external configurator may be used as a project configurator in Home Retailers. It must however respect the following interface, in the form of a list of supported iframe messages (postMessage API):

Listening

Output emitted by the project configurator at startup to indicate Home Retailers that it is ready

Key	Type	Value/Template	Description
event	string	Listening	–
content	–	–	–

ConfigureProject

Input emitted by Home Retailers to initialize the project configurator with data

Key	Type	Value/Template	Description
event	string	ConfigureProject	–
content	object	project: json object token: string configurationData: object	project: the Home Retailers full project token: the Home Retailers token. Should be used to authenticate to the ByMe API. configurationData: object containing the following data: - buildingIndex (number): the index of the current building displayed in HR when launching the configurator - levelIndex (number): the index of the current level displayed in HR when launching the configurator - nonConfigurableUuids (array of strings): the list of products UUIDs that do not belong to this configurator. These are products inserted from HR directly, or from another project configurator. You should not allow their modification in your configurator. - furnitureUuid (string): the UUID of a furniture from your configurator that the user wishes to edit specifically. This is not given the first time a user enters your configurator.

Template

{
    "project": { *bmproj_content* },
    "token": "xxxyyyzzz",
    "configurationData": {
        "buildingIndex": 0,
        "levelIndex": 1,
        "nonConfigurableUuids": [ "aaabbbccc", "dddeeefff" ],
        "furnitureUuid": null
    }
}

BadRequest

Output emitted by the project configurator when it encounters an error like a network issue.

This event will close the configurator and resume Home Retailers with no modification to the project. An error notification is displayed to inform the user.

Key	Type	Value/Template	Description
event	string	BadRequest	–
content	object	error: string	error: error message explaining the issue.

Template

{
    "error": "The detailed message of the encountered error."
}

Canceled

Output emitted by the project configurator when the user cancels the configuration.

This event will close the configurator and resume Home Retailers with no modification to the project.

Key	Type	Value/Template	Description
event	string	Canceled	–
content	–	–	–

ProjectSaved

Output emmited by the project configurator when the user validates the configuration.

Key	Type	Value/Template	Description
event	string	ProjectSaved	–
content	object	project: json object configurationData: object	project: the updated project (will be loaded by Home Retailers) configurationData: object containing the following data: - configuredUuids (array of strings): the full list of products UUIDs that are managed by this configurator - bom (object): the full BOM of this configurator. Must only include products whose UUIDs are in configuredUuids (do not price non-configured products) - projectInfos (object): the project infos of this configurator.

Template

{
    "project": { *bmproj_content* },
    "configurationData": { 
        "configuredUuids": [ "aaabbbccc", "dddeeefff" ],
        "bom": { *bom_content* },
        "projectInfos": { *project_infos_content* },
    },
}