Embed SDK
Use our Embed SDK to interact with calculators on your website.
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.
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
Get Element Instance
Retrieves a specific element from the calculator for interaction.
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.
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 |
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.
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 |
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.
The reference identifier for the element to update
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
Get Answer
Retrieves the current value of a specific element in the calculator.
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.
Set Answer for Element
Set a new value for a specific element in the calculator.
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
Get Interactive Elements
Retrieve all interactive elements from the calculator.
This method returns an array of all elements in the calculator that can be interacted with, such as input fields, dropdowns, and sliders.
Response
An array of objects, each representing an interactive element in the calculator.
Example
Get Custom Variables
Retrieve all custom variables defined in the calculator.
This method returns an array of custom variables that have been defined in the calculator configuration.
Response
An array of objects, each representing a custom variable in the calculator.
Example
Get Calculation Data
Retrieve the current calculation data from the calculator.
This method returns an object containing all the current values and calculated results in the calculator.
Response
An object containing the current state of the calculator’s fields and variables.
Example
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.
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
An object containing key-value pairs where keys are element references or variable names, and values can be of various types:
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:
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:
Now, let’s implement the ActiveCalculator integration:
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.
Was this page helpful?