START DOCUMENTATION

BITBYBIT VIEWER

This theme app extension block provides functionality to present 3D models as products without ever touching bitbybit.dev editors. You can upload your 3D models to Shopify CDN or any other publically available cloud storage and then use the url of the file to display it on the product page. This is the simplest way to present 3D models on your product page. We also allow you to load several 3D models at once via special JSON configuration.

Demo store product that uses BITBYBIT VIEWER block

Demo store product that uses BITBYBIT VIEWER block

Examples

Here are the few examples of demo store products that use BITBYBIT VIEWER block

Supported Formats

Currently, we support the following formats: gltf, glb, splat, ply, obj, stl.

How does it work?

First, you will need to upload your 3D model to Shopify CDN or any other publically available cloud storage. Then you will need to create a new product template and dynamically link "Model URL" setting of BITBYBIT VIEWER block to "3D Bits Model Url" product metafield. Then you can copy and paste the url of the 3D model to the 3D Bits Model Url metafield.

If you configured the VIEWER block correctly you should see this kind of output on your product template page.

BITBYBIT VIEWER block after dynamically linking all the settings to metafields

BITBYBIT VIEWER block after dynamically linking all the settings to metafields

When the linking of the settings is done correctly, you should be able to copy paste the file URL to the "3D Bits Model Url" metafield and see the 3D model on the product page after hitting preview.

Demo store product that uses BITBYBIT VIEWER block

Paste your file url's into this metafield

Using Scene Config JSON

Sometimes it is not enough to simply load a 3D model into your scene. You may want to customize things such as camera settings, lighting or even load multiple 3D models at once. This is where Scene Config JSON comes in. You can create a JSON configuration file that will allow you to customize your scene. You can load multiple 3D models, set camera settings, enable skybox, lighting and shadows.

Below we provide you with an example JSON configuration that you can use to load 3D models, configure camera and lighting. You can copy this JSON file to the "3D Bits Scene Config" metafield on your product page.

{ "$schema": "https://app.bitbybit.dev/assets/start/shopify/viewer-scene-config-schema-0-19-1.json", "models": [ { "url": "https://cdn.shopify.com/3d/models/ac59b22b4c310cdb/vases-serenity-5.glb", "position": [ 0, 0, 0 ], "rotation": [ 0, 0, 0 ], "scaling": [ 1, 1, 1 ], "animatedRotations": [ { "axis": "y", "speed": 0.01 } ] } ], "arcRotateCamera": { "position": [ 20, 15, -20 ], "target": [ 0, 2, 0 ], "angularSensibilityX": 3000, "angularSensibilityY": 3000, "lowerRadiusLimit": 1, "upperRadiusLimit": 150, "lowerBetaLimit": 40, "upperBetaLimit": 100, "panningSensibility": 4000, "wheelPrecision": 3, "maxZ": 100, "minZ": 0 }, "skybox": { "type": "greyGradient", "size": 1000, "blur": 1, "environmentIntensity": 0.7 }, "directionalLights": [ { "direction": [ -100, -100, -100 ], "intensity": 3, "diffuse": "#ffffff", "specular": "#ffffff", "shadowGeneratorMapSize": 3000, "enableShadows": true, "shadowDarkness": 0, "shadowUsePercentageCloserFiltering": true, "shadowContactHardeningLightSizeUVRatio": 0.2, "shadowBias": 0.0001, "shadowNormalBias": 0.02, "shadowMaxZ": 1000, "shadowMinZ": 0 } ] }

This is the metafield which you should use to paste the JSON configuration.

Paste your Scene Configuration JSON into this metafield

Paste your Scene Configuration JSON into this metafield

If you configured the template correctly and pasted this JSON configuration you should see the 3D model in the scene that has shadows and enabled rotation around y axis.

Demo store product that uses BITBYBIT VIEWER block and Scene Configuration metafield

Demo store product that uses BITBYBIT VIEWER block and Scene Configuration metafield

Editing JSON of scene config

You can edit JSON with any text editor. We recommend using Visual Studio Code or any other editor that supports JSON syntax highlighting. You can also use online JSON editors like jsoneditoronline.org to edit your JSON

To make your life somewhat easier when editing JSON, we set up basic schema which editors will parse and give you intellisense. You can find the schema here. Note that the schema may change in the future and you will need to update your scene description.

Make sure to also check this video tutorial that gives step by step guidance