Embed SDK

​

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.

​

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

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

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

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

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

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

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

​

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

​

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

​

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

​

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

​

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.

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

// 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:

// 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:

1. We define global default interest rates based on mortgage terms in global-config.js.
2. 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.