Products
The ByMe Platform makes it possible for consumers to experience products in a digital manner.
This section answers the following questions:
- What are these products? What information do they convey? How are they managed as a Product Range? When and where are they visible? What are the features that make it easier to manage the Range at scale?
Product Information Overview
Product fundamentals
A ByMe Product is the digital representation of a real-life retail product. As such it conveys:
- Descriptive information: short and long description in various languages, reference
- Commercial information: price(s), availability dates....
- Representation information: 3D Model (geometry or assembly), 2D model and thumbnail images
- Experience information: type, behaviors, rules, application-specific information
Some of these informations are mandatory or not, depending on the ByMe Product type, the application, the chosen range architecture, and the desired behaviors.
Note that product references must be unique in your range as some planner feature are based on the reference.
Simple product ranges are created easily in the ByMe information structure.
More elaborated Product Ranges may require more advanced notions such as Parameters, Generic Products, Overrides, Rules,
etc.
Product information display
Here are a few product information display examples, depending on the application:
Product detail
Parameters
Brand, Material
Tagging for CatalogEntries
Creating and Updating Products
Products are created and updated by Range Managers in one of the following ways:
- Manually, through 3DCloud
- Programmatically, through the ByMe API
Product Identification
Products are uniquely identified by the "id" attribute, typed String. This identifier is:
- the key to access products through APIs
- the attribute of inter-product pointers such as parameters, as well as catalogs, templates
The id of a product must be unique across all Legal Entities of the ByMe Platform (including potential other ByMe
customers), in order to support Cross-Legal Entity product reuse scenarios.
This uniqueness constraint is usually implemented by prefixing ids with the name of the Product’s Legal Entity in order
to avoid id collisions.
This attribute was previously referred to as "externalId".
Product Representation
Most ByMe products have a 3D representation used in the 3D planner and in high quality renders, and a 2D representation used on 2D plan exports. The ByMe Platform supports several representation formats :
- BM3, for 3D shape and material representation - see Geometry and Material Reference 🔗
- BMA, for 3D assemblies - see Assemblies 🔗
- BM3Mat, for materials.
These representations are edited in dedicated tools, and stored in files with the corresponding extension.
Several Products can be created with the same representation, but they become distinct copies, with distinct lifecycle ( updating the representation on one product will not update the others). Reuse of representations is best achieved by assemblies referencing a common product reference.
Product Classification and Typing
The ByMe platform provides several dimensions of product typing and classification.
Product / Generic Product: Class
Each product in the ByMe platform is either
- a (plain) Product, or
- a Generic Product. Generic Products are documented in the corresponding section 🔗
Main Type
The ByMe platform manages four main types of products:
| Main Type | Usage | Representations |
|---|---|---|
| 1 - Furniture | Used for furniture items: cabinets, sofas, decoration objects etc. | 3D: BMA, BM3 2D: BMA, BM3 or |
| SVG | ||
| 2 - Opening | Used to represent windows, doors, etc. | 3D: BMA, BM3 2D: SVG |
| 3 - Material | Used for shapeless products, such as floor of wall coverings | 2D: BM3Mat |
| 4 - Stair | Used to represent stairways | 3D: BMA, BM3 2D: SVG |
This main type is not set by the Range Manager, but inferred by the ByMe Platform from the typeID.
TypeID (main classification tag)
Products have a mandatory “typeID” attribute, which is used
- For product classification, in the product catalog hierarchy as displayed in the Application, as configured in the Application Distribution - please refer to the Application Distribution documentation for more details.
- For Application behaviors : Applications, such as HomeByMe for Kitchen Retailers, treat differently products of different types. It is therefore very important to set the type carefully based on Application Documentation. Moreover, a typeID might mandate some Product Parameters, as documented in the Applications’ Parameter Dictionary.
Here are some types examples :
| Main Type | Main Type name | typeID | typeID name |
|---|---|---|---|
| 1 | Furniture | 7 | Armchairs |
| 1 | Furniture | 12 | Wardrobes |
| 1 | Furniture | 22 | Base cabinets |
| 1 | Furniture | ... | ... |
| 2 | Openings | 245 | Double Interior Doors |
| 2 | Openings | 251 | Simple windows |
| 2 | Openings | 257 | Skylights |
| 2 | Openings | ... | ... |
| 3 | Material | 443 | Worktops |
| 3 | Material | 445 | Plinths |
| 3 | Material | 559 | Wallpanels |
| 3 | Material | ... | ... |
| 4 | Stairs | 298 | Helical Stairs |
| 4 | Stairs | 299 | Straight Stairs |
| 4 | Stairs | 300 | Quarterturn Stairs |
| 4 | Stairs | ... | ... |
The list of ByMe typeIDs may grow from time to time. There are around 300 at the time of writing. The list is accessible through the GET /tags API route, with type=”Type”. This API also provides with the mapping between typeIDs and Main Type.
Some applications can choose to make the typeID visible: it is thus translated. For example, it is available as a search filter in the HomeByMe search.
Closed Tags
Product tagging through Closed Tags allows Product classification and enhances search and discovery in applications. The following Closed Tags types are defined :
- styleTagIDs: modern, …
- roomTagIDs: kitchen,...
- colorTagIDs: red, green, blue, …
- materialTagIDs: wood, oak, …
The list of typeID possible values is fixed. It may grow from time to time. The list is accessible through the GET /tags API route. Closed Tag information is visible to the user in certain Applications, it is therefore translated and searchable. Setting these tags on a Product is not mandatory.
Our recommendation is to set Tags on your Products even if your current App does not display them, because
- Your current Application may leverage them in the future,
- Your products may be published on homebyme.com in the future.
We cannot emphasise enough how a well tagged product will surface more often in relevant contexts.
Free Tags
As their name implies, free tags can be set on Products without semantic constraints. Free Tags are used for:
- Product browsing hierarchy beyond the second level - refer to the Application Distribution documentation for this point;
- Product search filters - refer the to the documentation of your Application;
- Customer-specific Range Management scenarios (see also customerMetadata for these scenarios).
It is recommended to limit the number of Free Tags to 10 per product, and their names to 20 characters.
Product Family
When a same product model is provided in different sizes or colors, Range Managers should set a common Product Family
value on each of them.
Applications typically show links between the Products of the same Product Family.
Advanced configurability scenarios also can use Parameters, described in the Parameters chapter.
Making Products Visible to End-Users
By default, Applications’ search and browse features do not expose newly created Products. This section details how to explicitly make Products visible to end users.
Preamble : ByMe Product lifecycle
- There is a period of time BEFORE a product is visible to ByMe users, typically because the ByMe range is being built and validated, or because the retail item is not yet on sale;
- There is a period of time AFTER a Product is visible to ByMe users, typically because the Product is not sold anymore. ByMe projects containing legacy products can still be opened and displayed since Products are not deleted.
- Some Products are NEVER visible, for example reusable components that are only shown through assemblies. They are typically in Catalogs which are not associated to any Application Distribution.
This is why the ByMe Platform gives you control on Product visibility.
Publishing products in catalogs
Product <--> Product Catalog <--> Application Distribution
In order for a product to be visible in a ByMe application distribution,
- The product needs to belong to a product catalog (from the same Legal Entity), AND
- The product catalog needs to belong to an application distribution
Product availability dates
A product should have defined and valid startDate and endDate in order to be visible.
There is no implicit behavior on empty values - a null endDate does not mean “forever”, and both dates need to be set.
ByMe automatically makes the Product available to Applications at startdate 0:00 UTC, making it possible to program the actual publishing of a Product to consumers.
Catalog availability dates
⚠️ DEPRECATED
A Product Catalog used to have the possibility to define startDate and endDate as well. Both had to be defined and non null.
The following table describes which dates are considered for visibility, as a function of wether the Product dates and / or the Product Catalog dates are set :
| Product visibility is... | Product dates null or single | Product dates valid |
|---|---|---|
| Catalog dates null or single | Product is invisible | Based on product dates |
| Catalog dates valid | Based on Catalog dates | Based on product dates |
| Product belongs to several catalogs with valid dates | Based on min and max of all catalog dates | Based on product dates |
The “availability” flag
Range Managers can leverage the “availability” flag to disable a Product which would otherwise be visible due to the Catalog and dates criteria.
Deletion
The ByMe API Product delete route actually performs a “soft deletion” : the Product and its assets are kept, but marked as deleted.
An Application can open a Project containing deleted Products without error, and may suggest the replacement of deleted products.
Most features and API routes do not show deleted Products. Some routes show them with the “isDeleted” attribute set.
The product ID is not freed by deletion. No new Product can use the ID of a deleted Product.
The behavior of ByMe in case of links (Override, Parameter value, Generic Product mapping) from a Product to a deleted Product is unspecified. It is the responsibility of the Range Manager to perform consistent deletions.
DateUpdate
Products carry a dateUpdate attribute, which is exposed to Range managers, and also implicitly by Applications showing “recent content”. DateUpdate is updated when:
- The Product itself is updated
- Its linking or unlinking to Product catalogs is modified.
Products, Range Scalability and Range architecture
Simple customer Product ranges can be expressed by plain ByMe Products. However several fundamentals have been introduced in the ByMe platform to enable leverage and scalability in Range Management of functionally richer Product Ranges, if needed. These fundamentals are detailed in the following chapters :
- Parameters,
- Assemblies,
- Override,
- Generic Products.