Calls-to-action JavaScript API
The Calls-to-action JavaScript API allows you to render HubSpot Calls-To-Actions on your website. You can use this API to programmatically control when a CTA appears or listen to events triggered when a user interacts with one of your CTAs.
The API is housed in the window.HubSpotCallsToActions
object, which provides access to all available methods. The object is created by the HubSpot tracking code, but may not be available immediately on page load. To defer accessing the API until it's initialized, you can use the window.hsCallsToActionReady
helper.
window.hsCallsToActionReady
is an optional field you can define on the window
object which enables you to specify code to be executed as soon as the API becomes available. If used, this field should be set to an array of functions. Once the API has been initialized, this event handler will check for the existence of this array and execute the functions in order.
HubSpotCallsToActions.refresh
Refresh and re-render CTAs, given the current page URL.
If you're using CTAs in a single-page application, this function can be useful to refresh the CTAs shown based on a route change (i.e., dynamically show a CTA based on a specific route). If HubSpotCallsToActions.refresh is called on a route where there are no CTAs present, any visible CTAs will be removed.
HubSpotCallsToActions.close
Closes a specific CTA based on its ID. Display frequency rules will be applied to a CTA once it's closed. Calling this function will have no effect on embedded CTAs.
HubSpotCallsToActions.closeAll
Close all CTAs on a page. Calling this function will have no effect on embedded CTAs.
HubSpotCallsToActions.on
Register an event listener that will fire based on two arguments:
event
: the name of the event you want to define the handler for, provided as a string.handler
: a function that defines the behavior you want to occur when theevent
fires.
See the example snippet below for an example of defining a handler for the onCallToActionReady event. You can also review a full list of events you can define handlers in the table below.
HubSpotCallsToActions.off
Unregister a previously registered event listener
event
: the name of the event you want to unregister your previously defined handler for.handler
: a function that will fire when successfully unregistered.
CTAs will emit various events throughout its lifecycle. These events are defined in the table below. You can define listeners for each of these events using the HubSpotCallsToAction.on
function, as described in the section above.
Event name | Description |
---|---|
onCallToActionReady |
The CTA has finished loading, and has been fully rendered. |
onCallToActionViewed |
The CTA has entered the user's viewport. This event will only fire once. |
onCallToActionNavigated |
A link was clicked within the CTA. |
onCallToActionFormSubmitted |
A form within the CTA was submitted. When triggered, the event payload will include the formId . |
Events will also be posted to the parent window, which you can define listeners for using window.addEventListener.
For example, the snippet below defines an event listener that checks for the onCallToActionReady
event being emitted.
Thank you for your feedback, it means a lot to us.