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 endpoint to use depends on the integration context. Please contact your 3DVIA counterpart for more information. See also iFrame messages documentation and Secure your iFrame integration.

Reading direction

The Home Planner can display only reading direction Left To Right (LTR) for latin languages. The routes to use are:
▪ Left To Right: https://home.enterprise.by.me/Planner/

Language

The language of the content of the Home Planner is optionally set via a query parameter:

Key	Type	Description
In	String	Combination of: ▪ MANDATORY: 2 letter code of a language, following ISO 639-1 ▪ OPTIONAL: 2 letter code of a region / country, following ISO 3166-1 Those two elements are joined in a string and separated by a "-" (dash). ▪ Example 1: "en-US" ▪ Example 2: "fr-FR"

If not set, the Home Planner uses the language of the active locale of the targeted Application Distribution.

▪ Application in LTR and French: https://home.enterprise.by.me/fr-FR/

▪ Application in LTR & French as default language of the targeted Distribution: https://home.enterprise.by.me/

Load Project

There are three ways to open a project in the planner:

▪ When launching the planner from website, passing the project ID in the URL via a query parameter projectid using the project identifier as value.

Sample : https://home.enterprise.by.me/?projectId=8401

Note: The default project will be loaded if the project Id is not given, not found or if there is an error in loading the specified project.

▪ After the planner is initialized, with the LoadProject iFrame message this method is the only way to load a new project while already in the planner.

Note: When using this method to open a project with planner in it, the planner will load the default project, and then when ready it will load the provided project. It can thus affect startup performances when compared to the first approach (projectID in the URL).

▪ When launching the planner from website, passing the project ID and high-quality image ID in the URL via a query parameter projectid and HQRDbID. You can open the planner with the point of view of the requested high quality rendering image.

Sample : https://home.enterprise.by.me/?projectId=7118&HQRDbID=31286

Note: The image ID must be correct, if not, there will a network error with loading the project.

Beta feature flag

Some upcoming features that affect user experience in Home Planner may be hidden behind a feature flag. To be able to see them, you have to integrate the Home Planner in your iFrame with an extra URL parameter: "homeBeta".

Application in beta mode: : https://home.enterprise.by.me/?homeBeta

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/?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.

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