Runner Versions

The runner is the engine that loads and draws your configurator on the storefront. Each release of 3D Bits ships a new one. Your storefront does not move to it by itself: it keeps loading the version your theme saved, until you change it.

3D Bits tells you when that version has fallen behind. This page explains what the notice means, why nothing was updated for you, and how to update safely.

What the app shows you

Every place that names a runner version also says which version is the latest, with a badge for how far behind yours is:

Badge	Colour	Your version is
Latest	Green	The latest, or following each release
Slightly older	Light green	Less than two minor versions behind
2+ versions behind	Yellow	Two or three minor versions behind
4+ versions behind	Orange	Four or more minor versions behind
A major version behind	Red	From an earlier major version

When a published configurator loads a runner older than the latest, you see it in four places:

• Home shows a notice such as "1 configurator runs an older 3D runner (v1.4.0) - the latest is v1.6.2". It lists each configurator, where its version is saved and which version that is, with Test in the editor and Open theme editor beside it. Closing the notice hides it until the next release. The notice turns orange once a configurator is four minor versions behind, and red, with no way to close it, when one is a major version behind.
• Projects shows a badge such as "Runner v1.4.0 - latest v1.6.2" on each such project, in the colour above.
• A project's page says, under Show it on the product page, which runner the configurator loads and where, for example "3D runner on App embed: v1.4.0 - the latest is v1.6.2". Where it can, it offers the update right there - see Updating one configurator from the app.
• Storefront display has a Runner versions card listing every place your live theme loads the runner, with the version saved there and its badge.

The check reads your live theme. A draft theme is not looked at.

What each version reading means

The app says	What your theme saved	What happens on a release
A version, such as "v1.4.0"	A Runner CDN Link pointing at that release	Nothing. The storefront keeps that version
"follows the latest release"	An empty Runner CDN Link	The storefront moves to the new runner when the app updates
"your own link - 3D Bits cannot tell its version"	A link to your own CDN, or any address 3D Bits does not publish	Nothing. You host and update it yourself

Only the first row can be called older. An empty link and your own link are never reported.

If a project's page says "3D runner: no place in the live theme shows this configurator yet", the app read the whole live theme and found no enabled app embed or block for it, so there is no version to report. A block inside a hidden section counts as switched off, as the section is.

If it says the app could not tell where the live theme shows the configurator, part of the theme could not be read, or the theme has more files than the app reads. Nothing is known to be wrong: the Runner versions card on Storefront display lists what was found.

A block that shows a file of its own, such as an address you typed into its settings that is not a published 3D Bits project, is listed on that card but is not counted against any project.

Why 3D Bits does not update it for you

A newer runner can change how a configurator draws or computes: a newer 3D engine, changed defaults, a fixed bug your configurator happened to rely on. Most configurators are unaffected. The ones that are affected are affected on a live product page, in front of shoppers, and that is not a change to make without you.

So the version is yours to move. A saved link stays on its version, which is what keeps a configurator that works today working tomorrow.

There is also a practical reason. The version lives in your theme, and 3D Bits has permission to read your theme, not to change it. What the app can do, once you have tested, is set a version for one configurator that your storefront uses in place of the theme's - without touching the theme.

Test first, in the Composer

The Composer always runs the latest runner, and so do the script editors. Opening a project there and pressing Play shows you that configurator on the newest version before any shopper sees it.

1. Press Test in the editor beside the configurator in the notice, or open the project from Projects.
2. Press Play and work through the configurator the way a shopper would: every option, the price, any PDF or screenshot it offers. The editor does not add anything to a real cart, so the cart itself is checked in step 4.
3. If something looks or behaves differently, fix it in the editor and publish again before you update the storefront.
4. After you update, add the configured product to the cart once on the storefront and look at the cart.

A configurator that runs your own scripts deserves the most care here, since scripts reach furthest into the engine.

Updating the version

There are two ways: one configurator at a time from the app, or the link saved in your theme.

Updating one configurator from the app

When a configurator loads an older runner through 3D Bits' own link, its project page offers the update under Show it on the product page:

1. Test the configurator in the Composer, as above.
2. Tick I tested this configurator in the Composer, which runs the latest runner.
3. Press the button below it, which reads "Update this configurator to" followed by the latest version.

3D Bits checks that the files of that version are being served, then saves the version for this configurator. From then on your storefront loads that version for it, in the app embed and in a BITBYBIT VIEWER block on its product's template. Your theme is not changed, and your other configurators keep the version the theme saved for them.

The page then reads "This configurator is set to runner v1.6.2 in 3D Bits, which takes the place of the version saved in your theme", and the place it applies to carries a Set in 3D Bits badge. A configurator set this way stays on that version. When a later release arrives, the notice returns and the same button offers the next one.

Some places keep the version saved in the theme, and the page says so when one of them is older:

• a Runner CDN Link that points at your own CDN, or at one runner file;
• a block with a published address pasted into it, on any page;
• the BITBYBIT RUNNER block.

Change those in the theme editor, as described next.

In the theme

Where you change it depends on where the app says the version is saved.

App embed

1. Press Open theme editor beside the entry. It opens your live theme's App embeds.
2. Open the 3D Bits embed's settings and find Runner CDN Link.
3. Clear the field to follow each release from now on, or type the address of the release you tested, in the form https://git-cdn.bitbybit.dev/v followed by the version.
4. Save the theme.

The embed's link applies to every configurator shown through the embed, so test each of them first. To try the change without touching the live theme, make the same edit on a duplicate of your theme and preview it.

A block on a template

1. Press Open theme editor beside the entry. For a block on a template it opens that template. For a block in a section group, such as the header, it opens the theme editor, and you go to the section yourself.
2. Select the BITBYBIT VIEWER or BITBYBIT RUNNER block and find Runner CDN Link.
3. Clear it or set it to the release you tested, then save.

Each block has its own link. A block on a product template applies to the products using that template. A block you placed on another page with a published address pasted into it applies to that page only.

Common settings describes the Runner CDN Link field in full, including self-hosted links.

Going back

If you updated a configurator from the app, press Use the theme's version again on its project page. The storefront returns to the version your theme saved.

If you changed the link in the theme and a configurator misbehaves, put the previous address back in the same field and save. The older runner stays available at its address, so the storefront returns to exactly what it loaded before.

Following every release, or pinning one

	Empty link	A pinned version
New features and fixes	Arrive with each app update	Arrive when you move the link
Risk of a surprise on a live page	Small, but possible on a release	None until you move the link
What you do on a release	Check your configurators soon after	Test in the Composer, then update

A store with a few straightforward configurators is usually well served by an empty link. A store whose configurators carry scripts, pricing or a lot of custom logic is better pinned, tested and moved deliberately.

Related

Storefront display covers the app embed and the Runner versions card. The app embed lists the embed's settings.