released

Integrate the Home Planner to your Website

This section explains how to integrate the Home Planner in a website through iFrame mechanism. It provides guidance to create the user's projects page, build the print command, display the price details and implement online buying.

 

iFraming Home Planner

A website offering access to the Home Planner must embed it in an iFrame.

The Home Planner only supports the Left To Right (LTR) reading direction, for latin languages. The route to use is (match the case):
https://xxx.enterprise.by.me/Planner/

The xxx part depends on the integration context. Please contact your 3DVIA counterpart for more information.

You can append some parameters to this endpoint URL, in order to give context to the planner. See the supported URL parameters 🔗 for more information.

Secure your iFrame integration

The ByMe platform checks consistency between declared domains of your legal entity and application integration domain. There are three kind of situations:

▪ If declared domains and integration domain are NOT CONSISTENT, application startup will FAIL with a CORS origin issue. This behavior prevents someone else embedding your application distributions.
▪ If declared domains and integration domain are CONSISTENT, application will launch NORMALLY.
▪ If no domain is declared, the application will launch with a warning: "Unsafe integration: Please review iFrame integration and domain declaration"

It is highly recommended that you declare your embedding domains to the ByMe platform by using POST /legals/domains.

User's Projects Page

The integration Website displays page allowing user to manage his projects. Here are the useful API to build this page and manipulate the user's projects.

Retrieve the list of user's project : GET /projects/user/{userID}

Load a project by opening an URL composed of the Home Planner URL appended with a projectid parameters and the project uuid as value. Sample : https://home.enterprise.by.me/Planner/?projectid=8401

Enable the optional action "delete a project" : DELETE /projects/{projectID}/user/{userID}

Enable the optional action "duplicate a project" to duplicate an existing project and all its parameters to a new project : PUT /actions/projects/{id}/duplicate

Retrieve project media, thumbnails, HQ renderings, 360 renderings with : GET /projects/{projectID}/media. See also GET /typemedia for possible media types.

Thumbnails are generated when the user saves the project, using the current point of view. Two thumbnails are generated with resolutions of 427x320 and 1024x768. The recommendation is to use the lowest resolution in the context of user's project page.

High Quality image and Panoramic rendering (360) generation are triggered through their own layer in the planner. In order to improve the quality of the preview it is recommended if available to use an High Quality image as the project preview.

Project Page

The integration Website displays a project page. Here are the useful API to build this page and manipulate this project.

Retrieve basic information about a project, name, description, date of creation,... GET /projects/{projectID}

Retrieve project metadata, which contains Bill Of Material (BOM) with GET /projects/{projectID}/metadata/{applicationID}}

From the project page, the user can modify the project name or description. Use PUT /projects/{projectID}.

From the project page, the user can modify the project's notes. First display the existing project notes retrieved with
GET /projects/{projectID}/metadata/{applicationID}}. Second, once modified by the user update the project notes with PUT /projects/{projectID}/metadata/{applicationID}}

The project page can display the media, thumbnails, HQ renderings, 360 renderings retrieved with : GET /projects/{projectID}/media. See also GET /typemedia for possible media types.

Project Overview

ProjectOverview enables user to have an overview of project, it brings together a lot of information like name, description, price, medias, product list etc.

When clicked on Project Overview if the application distribution parameter projectOverview 🔗 is set to false, then iFrame message ProjectOverviewButtonClicked 🔗 is received as the output.

Product Sheet

The printing of the project is implemented by the integration developer in order to respect the way in which the home retailer wishes to present the project to the consumer. Usually the print creates a document containing home retailer logos, project snapshot, product list with prices, 2D Plans and notes. The project print is used by the consumer to make a purchase decision but also by the home fitter to install the home in consumer's home.

Events Sequence

  1. The user clicks "i" button. The planner emits the event SpecialProductInfoRequested.

  2. The embedding web site listens to the events SpecialProductInfoRequested. Product Sheet Layer displays the generated content to the user for review and adjustment.

Print

The printing of the project is implemented by the integration developer in order to respect the way in which the home retailer wishes to present the project to the consumer. Usually the print creates a document containing home retailer logos, project snapshot, product list with prices, 2D Plans and notes. The project print is used by the consumer to make a purchase decision but also by the home fitter to install the home in consumer's home.

Events Sequence

  1. The user clicks "Print" button. The planner emits the event PrintButtonClicked.

  2. If the project is saved the planner emits a second event ProjectSavedRequestForPrint.

  3. The embedding web site listens to the events PrintButtonClicked and ProjectSavedRequestForPrint. If both events are received the project is saved and ready to print. The embedding web site displays the print layer and starts collect data to create the printed document. Go to Step 5.

  4. If only the event PrintButtonClicked is received the project is not saved and cannot be printed immediately. The embedding web site has to trigger the save on the planner by sending SaveRequested, in response the planner emits SaveSucceeded.

  5. Print layer collects the data from the planner and build the printed content. Depending of the data required, it triggers messages and listens to their responses.

  6. Print layer displays the generated content to the user for review and adjustment. It presents a button to send the document to the printer or to retrieve it in PDF format.

Cookies and Browser Storage

The purpose of this section is to precise the Home Planner usages of cookies and browser storages. Especially regarding data kept by the browser when the application is closed.

Cookies

None.

Local Storage

hbm-webapp-project__uXX_pXXXX

This key is used to store a copy of the project in the browser local storage. It is used when the browser session is interrupted while the project is modified and not saved. After interruption, if the user restart the Home Planner, s/he is prompted and s/he can select to restart his project from this local copy. This project copy is updated after each modification and cleaned-up after a save.

Session Storage

None.

Library

Website:

Website could be default Website powered by 3DVia, or any client Website where embed the HomeByMe For Home Retailers planner.

Home Planner:

HomeByMe for Home Retailers planner

← PreviousNext →