SDK versions and updates

One version, always current

Your Mindset host serves the SDK. There is one build at a time, the one that matches the platform version on that host, and no older version to pin to. There is no npm package and no version number in the address.

The scripts are served with Cache-Control: no-cache, must-revalidate and an ETag that changes with every Mindset release. The browser checks with your host on every page load. When nothing changed, the host answers 304 Not Modified and the browser uses its cached copy. After a release, the next page load gets the new build.

A tab that is already open keeps running the build it loaded. So for a while after a release, an older SDK build can be talking to a newer Mindset. That is why the SDK only ever changes additively.

What can change, and what can't

New things can appear: events, fields on events, error codes, methods. Existing ones keep their names and shapes.

Write code that copes with that:

• Switch on event.type, and ignore types you don't recognize. Keep a default branch.
• Treat an unknown mindset:error code or run_error reason as a general failure.
• Ignore fields you don't use. Don't reject an object because it has more fields than you expected.
• Use only documented members. Your editor may offer others. They are internal and can change without notice.

The theming channels are the exception. The list of --ch-* channels follows the interface and can grow, so don't treat it as fixed. A channel you don't set keeps its default.

Which build is this page running

Quote these when you contact Mindset support.

version is the Mindset release, such as 1.4.42. commit is the source commit the build came from. buildTimeMs is when it was built, in milliseconds since 1970, so you can compare two builds.

// Drop-in element
const { version, commit, buildTimeMs } = window.MindsetAgentSDK;
console.log(`Mindset SDK ${version} (${commit}), built ${new Date(buildTimeMs).toISOString()}`);

// UI-less client
import { version, commit, buildTimeMs } from "https://eu.mindset.ai/sdk/mindset-agent-uiless.js";
console.log(`Mindset SDK ${version} (${commit}), built ${new Date(buildTimeMs).toISOString()}`);

window.MindsetAgentSDK also carries tag (the registered tag name, mindset-agent), define(), and the MindsetAgentElement and MindsetAgentTagCollisionError classes.

Load the script once

mindset-agent.js registers the <mindset-agent> tag. The browser lets a page register a tag name only once, so load the script exactly once per page.

Loading it twice isn't harmless. A second copy of the script:

• logs a MindsetAgentTagCollisionError in the console. Its message blames "a v2 embed", but here the cause is the duplicate script
• replaces window.MindsetAgentSDK with the second copy, so el instanceof MindsetAgentSDK.MindsetAgentElement is false and MindsetAgentSDK.define() throws
• downloads and runs the whole bundle, React included, a second time

The element keeps working, on the first copy's code. Remove the second script tag, or make sure the code that loads the script runs only once. Use it with React and Vue has a loader that does.

Never add mindset-agent-charts.js yourself. The element loads it from your Mindset host the first time it draws a chart. It registers no tag, so it can't collide. But added by hand before the element has set up, it throws an error and loads nothing.

Another Mindset embed on the same page. An older Mindset embed that also registers mindset-agent stops this one registering. The console shows the same collision error, naming the tag and this build's version. Load only one Mindset SDK per page.

To check registration from code, call MindsetAgentSDK.define(). It returns false when this build already registered the tag, and throws MindsetAgentTagCollisionError when something else holds it.

Related

• How embedding works for the two ways to embed.
• Errors and resilience for handling every error.