Embed SDK - ActiveCalculator Docs

Embed SDK is available only to paid plans.

Overview

Our Embed SDK lets you interact with calculators embedded on your web pages. It provides methods to listen for changes, access elements, and update values, giving you full control over your embedded calculators.

If you embedded your calculator before August 26, 2024, you may need to update the embed code on your website. The new embed code now includes the Embed SDK automatically. Previously, only the iframe code was provided.

To use the Embed SDK, toggle the “Enable JS API” option in your calculator settings.

Methods

Initialize Embed SDK

The SDK automatically initializes when the calculator is embedded on your page. You don’t need to call an explicit init function.

Get Calculator Instance

Retrieves an instance of the calculator for interaction.

const calculatorInstance = activeCalculator.getInstance("YOUR_CALCULATOR_ID");

calculatorId

string

required

The unique identifier for your calculator instance

This method returns a calculator instance that you can use to interact with your embedded calculator.

Wait for Calculator Ready State

window.addEventListener("activeCalculatorReady", function () {
  const calculatorInstance = activeCalculator.getInstance("YOUR_CALCULATOR_ID");
  // Your code here
});

Get Element Instance

Retrieves a specific element from the calculator for interaction.

const element = calculatorInstance.getElementInstance("ELEMENT_REF");

elementRef

string

required

The reference identifier for the specific element within the calculator

This method returns an element instance that you can use to interact with a specific part of your calculator.

Listen for Calculator Events

Sets up a listener for calculator-wide events.

calculatorInstance.on("interaction", function (response) {
  const { elementReference, value, calculationData, responseData } = response;
  console.log("Interaction detected:", elementReference, value);
});

event

string

required

The name of the event to listen for (e.g., “interaction”). Only the “interaction” event is supported at the moment.

Event	Description
interaction	Triggered when a visitor interacts with the calculator

handler

function

required

The callback function to execute when the event occurs

This method allows you to react to any interaction within the calculator.

Listen for Element Events

Sets up a listener for events on a specific element.

const element = calculatorInstance.getElementInstance("ELEMENT_REF");

element.on("valueChange", function (data) {
  console.log("New value:", data.value);
  console.log("Calculation data:", data.calculationData);
  console.log("Response data:", data.responseData);
});

event

string

required

The name of the event to listen for (e.g., “valueChange”). Only the “valueChange” event is supported at the moment.

Event	Description
valueChange	Triggered when the value of the element changes

handler

function

required

The callback function to execute when the event occurs

This method allows you to react to changes in a specific element of the calculator.

Set Answer

Sets the value for a specific element in the calculator.

calculatorInstance.setAnswer("ELEMENT_REF", newValue);

elementRef

string

required

The reference identifier for the element to update

newValue

union

required

The new value to set for the element. The type depends on the element:

For number and range slider inputs: number
For text inputs (email, phone, website, short text, long text): string
For file upload: string[]
For select and radio button: { id: string; value: number; label: string; }
For checkboxes: { id: string; value: number; label: string; }[]

This method allows you to programmatically update the value of a specific element in the calculator.

Examples

calculatorInstance.setAnswer("NUMBER_INPUT_REF", 42);

Get Answer

Retrieves the current value of a specific element in the calculator.

const currentValue = calculatorInstance.getAnswer("ELEMENT_REF");

elementRef

string

required

The reference identifier for the element to retrieve the value from

This method returns the current value of a specific element in the calculator.

Additional Methods

Get Answer from Element

Retrieve the current value of a specific element in the calculator.

const currentValue = element.getAnswer();

Set Answer for Element

Set a new value for a specific element in the calculator.

element.setAnswer(newValue);

newValue

union

required

The new value to set for the element. The type depends on the element:

For number and range slider inputs: number
For text inputs (email, phone, website, short text, long text): string
For file upload: string[]
For select and radio button: { id: string; value: number; label: string; }
For checkboxes: { id: string; value: number; label: string; }[]

Examples

const numberInputInstance = calculatorInstance.getElementInstance("NUMBER_INPUT_REF");
numberInputInstance.setAnswer(42);

Get Interactive Elements

Retrieve all interactive elements from the calculator.

const interactiveElements = calculatorInstance.getInteractiveElements();

This method returns an array of all elements in the calculator that can be interacted with, such as input fields, dropdowns, and sliders.

Response

interactiveElements

array

An array of objects, each representing an interactive element in the calculator.

Show properties

ref

string

The unique reference identifier for the element.

type

string

The type of the interactive element (e.g., “rangeSlider”, “number”).

title

string

The display title of the element.

variable

string

The variable name associated with the element.

settings

object

An object containing the specific settings for the element.

Example

[
    {
        "ref": "ArOP8",
        "type": "rangeSlider",
        "title": "Range Slider",
        "settings": {
            "max": 100,
            "step": 1.5,
            "prefix": "$",
            "variant": "default",
            "defaultValue": 0,
            "decimalPlaces": 2,
            "alwaysShowValue": true,
            "displayValueEditable": true
        },
        "variable": "rangeSlider"
    },
    {
        "ref": "LLAR-",
        "type": "number",
        "title": "Number",
        "settings": {
            "defaultValue": 0,
            "useMouseControls": true
        },
        "variable": "number"
    }
]

Get Custom Variables

Retrieve all custom variables defined in the calculator.

const customVariables = calculatorInstance.getCustomVariables();

This method returns an array of custom variables that have been defined in the calculator configuration.

Response

customVariables

array

An array of objects, each representing a custom variable in the calculator.

Show properties

string

The unique identifier for the variable.

title

string

The display title of the variable.

variable

string

The name of the variable used in calculations.

expression

string

The mathematical expression used to calculate the variable’s value.

Example

[
    {
        "id": "EX1Ap",
        "title": "Loan",
        "variable": "loan",
        "expression": "100 * @number"
    }
]

Get Calculation Data

Retrieve the current calculation data from the calculator.

const calculationData = calculatorInstance.getCalculationData();

This method returns an object containing all the current values and calculated results in the calculator.

Response

calculationData

object

An object containing the current state of the calculator’s fields and variables.

Show properties

fields

object

A record of all interactive elements in the calculator.

Show value types

number

A numeric value for number inputs.

string

A string value for text inputs.

string[]

array of strings

An array of strings for multi-select inputs.

number[]

array of numbers

An array of numbers for numeric multi-select inputs.

option

object

An object representing a single selected option.

Show Option Properties

string

The unique identifier of the option.

value

number

The numeric value associated with the option.

label

string

The display label for the option.

option[]

array of objects

An array of option objects for multi-select inputs.

variables

object

A record of all calculated variables in the calculator.

[variableName]

number

The calculated value for each variable.

Example

{
    "fields": {
        "rangeSlider": 0,
        "number": 0
    },
    "variables": {
        "loan": 0
    }
}

This example shows a sample response from getCalculationData() and how to access the values in your code.

Get Response

Retrieve the current response data from the calculator.

const responseData = calculatorInstance.getResponse();

This method returns an object containing the current response data, which may include formatted results or additional information based on the calculator’s configuration.

Response

responseData

object

An object containing key-value pairs where keys are element references or variable names, and values can be of various types:

Show value types

boolean

A true/false value.

string

A text value.

number

A numeric value.

option

object

An object representing a selected option.

Show Option Properties

string

The unique identifier of the option.

value

number

The numeric value associated with the option.

label

string

The display label for the option.

option[]

array

An array of option objects for multi-select inputs.

any

Any other type of value not covered by the above.

Debug Mode

To enable debug mode in ActiveCalculator, add ?activeCalculatorDebug=true to your app’s URL. For example, if you’ve embedded your ActiveCalculator instance in your app hosted at https://example.com, you can activate debug mode by changing the URL to:

https://example.com?activeCalculatorDebug=true

After adding this parameter, refresh the page and open your browser’s developer console (usually by pressing F12 or right-clicking and selecting “Inspect” then navigating to the “Console” tab).

Example: Mortgage calculator

In this example, we’re showing how to make life easier for users by automatically filling in the interest rate when they pick a mortgage term. We’ve got default rates ready to go, but you can totally swap these out with fresh rates from your backend whenever you need to keep things up-to-date.

Mortgage calculator with custom backend rates

First, let’s set up our default interest rates based on mortgage terms:

global-config.js

// You can fetch the latest rates from your backend here
// Store default weekly interest rates based on mortgage terms
window.mortgageDefaults = {
  5: 2.75, // 5 years
  10: 3.25, // 10 years
  15: 3.75, // 15 years
  30: 4.25, // 30 years
};

Now, let’s implement the ActiveCalculator integration:

mortgage-calculator.js

// Wait for the ActiveCalculator to be ready
window.addEventListener("activeCalculatorReady", function () {
  // Get the calculator instance
  const calculatorInstance = activeCalculator.getInstance(
    "MORTGAGE_CALCULATOR_ID"
  );

  // Get specific element instances
  const mortgageTermSelect = calculatorInstance.getElementInstance(
    "MORTGAGE_TERM_SELECT_REF"
  );

  // Listen for value changes on the mortgage term select
  mortgageTermSelect.on("valueChange", function (data) {
    console.log("Mortgage term changed:", data.value);

    // Update the interest rate based on the selected mortgage term
    const defaultRate = window.mortgageDefaults[data.value.value] || 3.5; // Default to 3.5 if not found
    calculatorInstance.setAnswer("INTEREST_RATE_FIELD_REF", defaultRate);
  });
});

This example demonstrates a more realistic scenario for a mortgage calculator:

We define global default interest rates based on mortgage terms in global-config.js.
In mortgage-calculator.js, we set up the ActiveCalculator integration:
- We get instance of the mortgage term select field.
- We listen for changes on the mortgage term select and update the interest rate accordingly.

SDKs

​Overview

​Methods

​Initialize Embed SDK

​Get Calculator Instance

​Wait for Calculator Ready State

​Get Element Instance

​Listen for Calculator Events

​Listen for Element Events

​Set Answer

​Examples

​Get Answer

​Additional Methods

​Get Answer from Element

​Set Answer for Element

​Examples

​Get Interactive Elements

​Response

​Example

​Get Custom Variables

​Response

​Example

​Get Calculation Data

​Response

​Example

​Get Response

​Response

​Debug Mode

​Example: Mortgage calculator

Overview

Methods

Initialize Embed SDK

Get Calculator Instance

Wait for Calculator Ready State

Get Element Instance

Listen for Calculator Events

Listen for Element Events

Set Answer

Examples

Get Answer

Additional Methods

Get Answer from Element

Set Answer for Element

Examples

Get Interactive Elements

Response

Example

Get Custom Variables

Response

Example

Get Calculation Data

Response

Example

Get Response

Response

Debug Mode

Example: Mortgage calculator