Embed calculators with the loader
The embed loader is one script tag that puts Aztec-Calcs calculators into your web pages. It loads asynchronously and never throws an error into your page.
Before you start
You need:
- Your public key (
pk_...) and the loader URL. The Go live page in the portal shows both and builds the snippet for you. - The origin of your page in your allowed domains. Calculators on other pages don't load.
- A calculator group on your cobrand for each calculator you embed.
Minimal example
Add the loader script once, then add one container for each calculator:
<script async src="https://<your embed host>/v1/loader.js"></script>
<div data-aztec-calc="auto-loan-payment" data-cobrand-key="<your public key>"></div>
Replace the host and the key. The loader finds each container when the page loads, shows a grey loading placeholder, and mounts the calculator inside the container.
Options
Set these attributes on the container:
| Attribute | Required | Description |
|---|---|---|
data-aztec-calc | Yes | The calculator key, for example auto-loan-payment. Use 1 to 64 lowercase letters, digits and hyphens. |
data-cobrand-key | Yes | Your public key. It starts with pk_. |
data-locale | No | en-US, es-US, en-CA or fr-CA. The default is your cobrand's default locale. |
You can put several containers on one page, and each one mounts its own calculator. The loader fetches the calculator code once. It reads containers once, when the page loads. For containers you add later, see Mount calculators in single-page apps.
A calculator renders inside a shadow root. Your page's CSS can't restyle it, and its styles don't reach your page. The calculator takes your cobrand's branding and call-to-action buttons.
Errors and limits
The loader fails soft. When something goes wrong, it removes the placeholder, sets data-aztec-calc-state="Failed" on the container and writes one warning to the browser console. The warning starts with [Aztec-Calcs] and one of these codes:
| Code | Cause |
|---|---|
MISSING_ATTRIBUTE | data-aztec-calc or data-cobrand-key is missing. |
INVALID_COBRAND_KEY | The key isn't a public key, or no cobrand has it. A key that starts with sk_ is a secret key. Never use one in the browser. |
CALCULATOR_UNAVAILABLE | The calculator key has the wrong format, or your cobrand can't use it. |
DOMAIN_NOT_ALLOWED | The page's origin isn't in your allowed domains. |
LOAD_FAILED | The calculator code or definition didn't load, or the calculator failed to render. |
UNSUPPORTED_LOCALE | A warning only. data-locale is a supported option, but the loader drops a value that isn't one of the four locales and uses your cobrand's default locale. The calculator still loads. |
The container's data-aztec-calc-state attribute is Loading, Ready or Failed. Use it in your own styles or scripts.
| Limit | Value |
|---|---|
| Load time | 10 seconds for the calculator code and definition together. After that the container fails with LOAD_FAILED. |
| Pages | Calculators load once per page. A second copy of the loader on the same page does nothing. |
| Request rate | The calculator's requests count against your public key. See Rate limits. |
The loader's own origin serves the loader and the calculator bundle. The loader URL path always ends in /v1/loader.js.
Related API reference
The loader calls the embed endpoints. See Embed endpoints and allowed domains. The calculation operations are in the generated reference: