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");

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");

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);
});

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

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);
});

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

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);

string

required

The reference identifier for the element to update

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);

calculatorInstance.setAnswer("RANGE_SLIDER_REF", 75.5);

calculatorInstance.setAnswer("EMAIL_INPUT_REF", "user@example.com");

calculatorInstance.setAnswer("FILE_UPLOAD_REF", ["file1.jpg", "file2.pdf"]);

// First, get the interactive elements
const interactiveElements = calculatorInstance.getInteractiveElements();

// Find the select element by its ref
const selectElement = interactiveElements.find(element => element.ref === "SELECT_ELEMENT_REF");

// Get the first option from the select element
const selectOption = selectElement.settings.options[0];

calculatorInstance.setAnswer(selectElement.ref, selectOption);

// First, get the interactive elements
const interactiveElements = calculatorInstance.getInteractiveElements();

// Find the checkboxes element by its ref
const checkboxesElement = interactiveElements.find(element => element.ref === "CHECKBOXES_ELEMENT_REF");

// Get the first two options from the checkboxes element
const checkboxOptions = checkboxesElement.settings.options.slice(0, 2);

calculatorInstance.setAnswer(checkboxesElement.ref, checkboxOptions);

Get Answer

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

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

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);

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);

const sliderInstance = calculatorInstance.getElementInstance("RANGE_SLIDER_REF");
sliderInstance.setAnswer(75.5);

const emailInputInstance = calculatorInstance.getElementInstance("EMAIL_INPUT_REF");
emailInputInstance.setAnswer("user@example.com");

const fileUploadInstance = calculatorInstance.getElementInstance("FILE_UPLOAD_REF");
fileUploadInstance.setAnswer(["file1.jpg", "file2.pdf"]);

const selectInstance = calculatorInstance.getElementInstance("SELECT_REF");

// Get the interactive elements to access the options
const interactiveElements = calculatorInstance.getInteractiveElements();
const selectElement = interactiveElements.find(el => el.ref === "SELECT_REF");

// Get the first option from the select element
const selectOption = selectElement.settings.options[0];

selectInstance.setAnswer(selectOption);

const checkboxesInstance = calculatorInstance.getElementInstance("CHECKBOXES_REF");

// Get the interactive elements to access the options
const interactiveElements = calculatorInstance.getInteractiveElements();
const checkboxesElement = interactiveElements.find(el => el.ref === "CHECKBOXES_REF");

// Get the first two options from the checkboxes element
const checkboxOptions = checkboxesElement.settings.options.slice(0, 2);

checkboxesInstance.setAnswer(checkboxOptions);

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

array

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

Show properties

string

The unique reference identifier for the element.

string

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

string

The display title of the element.

string

The variable name associated with the element.

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"
    }
]

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

// Get element references
const rangeSliderRef = interactiveElements.find(element => element.type === "rangeSlider").ref;
const numberInputRef = interactiveElements.find(element => element.type === "number").ref;

// Use element references to get element instances
const rangeSlider = calculatorInstance.getElementInstance(rangeSliderRef);
const numberInput = calculatorInstance.getElementInstance(numberInputRef);

// Now you can interact with these elements
rangeSlider.on("valueChange", function(data) {
  console.log("Range slider value changed:", data.value);
});

numberInput.setAnswer(50);

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

array

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

Show properties

string

The unique identifier for the variable.

string

The display title of the variable.

string

The name of the variable used in calculations.

string

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

Example

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

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

console.log(customVariables[0].title);       // Output: "Loan"
console.log(customVariables[0].expression);  // Output: "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

object

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

Show properties

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.

array of strings

An array of strings for multi-select inputs.

array of numbers

An array of numbers for numeric multi-select inputs.

object

An object representing a single selected option.

Show Option Properties

string

The unique identifier of the option.

number

The numeric value associated with the option.

string

The display label for the option.

array of objects

An array of option objects for multi-select inputs.

object

A record of all calculated variables in the calculator.

number

The calculated value for each variable.

Example

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

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

console.log(calculationData.fields.rangeSlider);  // Output: 0
console.log(calculationData.variables.loan);      // Output: 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

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.

object

An object representing a selected option.

Show Option Properties

string

The unique identifier of the option.

number

The numeric value associated with the option.

string

The display label for the 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.

​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