Main concepts

All Fibbl components are custom HTML elements. It means that they can be used in the same manner as usual HTML elements are used: you can add standard attributes, such as id, class, aria-* etc., you can style the elements via CSS, and you can manipulate them via JS.

However, if you use a front-end framework, you should take into account that the elements currently don't support dynamic attribute changes.

How to use Fibbl components

1. You should add Fibbl scripts to your product pages. Each script must have the type="module" attribute (it's important). You can use fibbl.js, which contains all Fibbl components, or you can add separate scripts for each component that you want to use. Examples:

<!-- It's recommended to use fibbl.js, it defines all Fibbl components -->
<script src="https://cdn.fibbl.com/fibbl.js" type="module"></script>

<!-- Deprecated, not recommended: different scripts for different components -->
<script src="https://cdn.fibbl.com/model-viewer.js" type="module"></script>
<script src="https://cdn.fibbl.com/carousel.js" type="module"></script>

It's recommended to use fibbl.js rather than separate scripts. The only difference is the file size. But this difference is negligible, because some scripts include others, e.g. model-viewer includes qr-code, and fibbl-layer includes model-viewer. So model-viewer.js and fibbl-layer.js together are significantly bigger than fibbl.js.

WARNING: do not add Fibbl scripts via Google Tag Manager. If you do it, then some users, who have an ad blocker installed, may not see the Fibbl content, because some ad blockers (e.g. uBlock Origin) completely block the GTM script. And when the GTM script is blocked, no Fibbl scripts will be added.

2. It may be rather useful to include the following style tag along with the script:

   <style>:not(:defined){opacity:0;}</style>
   <!-- 
   The style above affects all custom elements, 
   if you want to hide only Fibbl undefined elements, 
   then use the following style 
   (you can list more Fibbl elements inside :is(), if needed)
   -->
   <style>:is(fibbl-bar, fibbl-layer):not(:defined){opacity:0;}</style>

   It can be especially handy when you use an element with custom markup (like the fibbl-bar). Before a script is loaded, that markup is shown with default styles, and the rule above hides it until a custom element is defined.

3. Some elements include others, e.g. fibbl-bar includes model-viewer, carousel and qr-code, so you don't need to include them separately, if you use fibbl-bar.

4. Use the element as any other HTML element - you can add styles, classes, event handlers and other valid html attributes to it. But do not forget that custom elements cannot be self-closed, that is, instead of <fibbl-element /> you should always write <fibbl-element></fibbl-element>.

Shared behavior

All Fibbl components work in the following way:

1. Initially a component renders itself completely transparent.
2. Then it checks availability of the product with the provided product id.
3. If the product is available, the component makes itself visible.
4. If not, the component hides itself. Currently, it's hidden with display: none, that is, not removed from the DOM. But this way of hiding can be changed in the future, so you must rely on it (e.g. using CSS sibling selectors).

Domain-based restrictions, demo models and demo company

By default, you can use models only on the website that corresponds to the company for which those models were purchased (it's done on the Client Portal).

For local development, you can use the token and secret.

Also, there are demo models that are available everywhere with no additional configuration. They are:

• @demo-shoe
• @demo-glasses
• @demo-bag

These strings can be used as the data-product-id attribute values.

Furthermore, there is a Demo company with the demo access token. It has the following models:

• shoe1, shoe2, shoe3
• glasses1, glasses2, glasses3

There are several features that cannot be viewed/tested in case of standalone demo models. The features are: product banner, product switcher and annotations.

To use the Demo company, use should use its token in the config:

<script 
  src="https://cdn.fibbl.com/fibbl.js" type="module"
  data-fibbl-config
  data-token="demo"
></script>
<fibbl-3d-quick-view data-product-id="shoe1"></fibbl-3d-quick-view>

Dynamic and static props

Fibbl components may have both dynamic and static props (data- attributes).

The first time an element is attached to the DOM, it initializes itself using all the attributes provided. But then it observes only dynamic props. If you change a static prop, it will not react.

If a prop is dynamic, it is mentioned explicitly in these docs. Otherwise, a prop is static.

If you want to update a static prop, then you have to recreate a component. In frameworks like React you should provide a new key to an element each time you need to update it.

API limitations

Do not use any props/methods/classes/components, which are not explicitly described in this documentation. Also, never send HTTP requests to the Fibbl backend endpoints (e.g. to get/check models) - the backend API is private and can be changed at any time.

If you find that the current API is not enough to implement what you want, please, don't try to bypass the limitations - ask Fibbl managers to enhance it. Otherwise, after an API update your workarounds can be broken.