ConvertFlow Javascript API examples
Once you've placed ConvertFlow's script on your website, you can access ConvertFlow's client-side Javascript API.
ConvertFlow Javascript API events
By hooking into the ConvertFlow Javascript events, you can use the Javascript API as well as capture event details upon CTA interactions.
cfReady - Fires when ConvertFlow's script has been fully initialized and indicates when the javascript API is ready to be used.
cfView - Fires when a CTA has been viewed and upon reaching each additional step.
cfConversion - Fires when a CTA has been engaged with, including button clicks, form submissions, and survey selections.
cfAnswer - Fires only when a quiz element question has been answered.
cfSubmit - Fires only when CTA form and survey elements have been submitted.
cfAddToCart - Fires only when ConvertFlow products elements, using the Shopify data source, have a product added to cart.
cfCompletion - Fires when the CTA has been tracked as completed by the "Track completion of CTA" automation. [Configuring completion tracking]
cfClose - Fires when the CTA has been closed by the popup X icon, or by an element set to close the CTA upon engagement.
How to access event details
If you want to access the fields collected by ConvertFlow forms upon submission with a site-wide script, you can hook into the cfSubmit event to access the latest conversion event with the data variable inside the conversion event callback. You can access the latest submitted field data with data.fields
jQuery(document).on('cfSubmit', function(event, data) {
// log latest conversion event in console
console.log(data);
});
If you're not using jQuery, the field data from the conversion event is accessed using event.detail and the field data is accessed using event.detail.fields
window.addEventListener("cfSubmit", function(event) {
// log latest conversion event in console
console.log(event.detail);
});
Pro tip: You can also add custom Javascript in each form element's completion script manager, which is a useful way to organize your scripts because it lets you run custom Javascript only when specific CTA elements are engaged with, or when specific CTA steps are viewed. Here's more info on using ConvertFlow's custom script management tools →
ConvertFlow Javascript API methods
Once ConvertFlow's Javascript API has initialized upon the cfReady event, you can use ConvertFlow Javascript API functions to control ConvertFlow programmatically:
convertflow.person - Returns the tracked data on the current visitor, such as fields and tracking metadata. [See example]
convertflow.load(payload) - Loads a CTA based on the given payload options. [See example]
convertflow.trigger(payload) - Triggers a loaded CTA based on the given payload options. [See example]
convertflow.start(); - Clears all CTAs from the page and loads CTA campaigns with the latest data. Useful for single-page applications. [See example]
convertflow.close(payload); - Closes popup CTAs that are currently triggered. [See example]
convertflow.identify(payload); - Identifies the current visitor with the email address in the payload. [See example]
convertflow.trackPurchase(payload); - Tracks a purchase. Will attribute revenue to campaign conversions within last 7 days [See example]
How to load popup CTAs with the API
Once ConvertFlow's script has finished loading, you can load a specific CTA onto the page by calling convertflow.load(payload)
window.addEventListener("cfReady", function(event) {
// load a popup CTA by replacing CTA_ID with ID found in CTA's dashboard URL
convertflow.load({cta_id: CTA_ID});
});
Note that the popup trigger settings of the popup CTA (not targeting conditions) will still apply, even if it's loaded via Javascript API. For example, if the popup is set to trigger after 5 seconds, it will still wait 5 seconds to trigger, even if loaded via javascript API.
convertflow.load(payload) also accepts a callback function, so you can do things once the CTA is loaded.
window.addEventListener("cfReady", function(event) {
// load a popup CTA by replacing CTA_ID with ID found in CTA's dashboard URL
convertflow.load({
cta_id: CTA_ID,
callback: function(cta, variant, embed) {
// do stuff
}
});
});
How to trigger popup CTAs with the API
convertflow.trigger(payload) can be used to trigger an already loaded CTA before it's triggered by the visitor.
For example, it can be used in the callback function of convertflow.load(payload) to trigger the popup programmatically.
Here's a full example of loading a CTA via the API and triggering it immediately.
window.addEventListener("cfReady", function(event) {
// load and trigger a popup CTA. Replace CTA_ID with ID found in CTA's dashboard URL
convertflow.load({
cta_id: CTA_ID,
callback: function(cta, variant, embed) {
convertflow.trigger({
cta_id: cta.id
});
}
});
});
convertflow.trigger(payload) also accepts a step position value, which will jump the CTA to the step position given. For example:
convertflow.trigger({
cta_id: CTA_ID,
step: 2
});
How to close CTAs using the API
convertflow.close(payload) can be used to close CTAs that are currently triggered.
Here's an example of closing all CTAs that are currently triggered, while tracking the close so the popups' aggressiveness settings are respected.
convertflow.close({
track: true
});
convertflow.close(payload) also accepts a cta_id value, which will cause the function to close only the CTA with the respective ID.
In this example, CTA_ID would need to be replaced with the CTA's ID (found in dashboard URL). Also, we're optionally not tracking the closing of the CTA, so it can be triggered again by the CTA's trigger settings. Example:
convertflow.close({
cta_id: CTA_ID,
track: false
});
How to access a visitor's personalization data
You can also access a visitor's data after the cfReady event has fired by calling convertflow.person.
window.addEventListener("cfReady", function(event) {
// log currently tracked data in console
console.log(convertflow.person);
});
You can use this to access the metadata and ConvertFlow contact fields associated with the tracked visitor.
How to identify contacts on your website
If you already have collected the email address or phone of your visitor (example: you're using ConvertFlow for logged in users in an app), you can tell ConvertFlow who the person is using the convertflow.identify function to pass one of the contact identifier fields, email or phone.
Here's a snippet you can use, just replace EMAIL_ADDRESS_HERE with a string of your contact's email address.
The option "override" can be set to false if you want to respect existing field values, such as if you only wanted identify if the visitor isn't already tracked as a contact.
Make sure to run this after the cfReady event by wrapping it with the given event listener.
window.addEventListener("cfReady", function(event) {
convertflow.identify({
email: 'EMAIL_ADDRESS_HERE',
override: true
});
});
Populating non-identifier fields
You can optionally pass non-identifier fields to the convertflow.identify function, to pre-fill your form fields and populate merge tags. For example:
window.addEventListener("cfReady", function(event) {
convertflow.identify({
email: 'EMAIL_ADDRESS_HERE',
name: 'Jane',
last_name: 'Doe',
company_name: 'ACME Inc',
company_title: 'Marketing Director',
url: 'acme-inc.com',
address: '123 Main Street',
city: 'Miami',
state: 'Florida',
zip_code: '55555',
country: 'United States',
custom_fields: {
team_size: '10-50',
revenue: '$10 million+'
}
});
});
Non-identifier fields will be used for pre-filling ConvertFlow form fields, populating merge tags and for targeting conditions that check contact fields, but they won't update in your contact database until the visitor explicitly submits the values through a ConvertFlow form.
How to initiate ConvertFlow with Javascript (for one-page apps)
If you use ConvertFlow in a one-page application, where navigating the app doesn't initiate an entire page load, you can manually initiate ConvertFlow's campaign targeting logic by calling convertflow.start()
For example, if you use Ruby on Rails, where Turbolinks is used to load only certain parts of pages upon page navigation, you can trigger ConvertFlow's campaign targeting logic to run on page change navigation in the page Turbolinks callback, like so...
jQuery(document).on('page:change', function() {
convertflow.start();
});
Tracking purchases for attribution
You can manually track purchases to attribute revenue to ConvertFlow campaigns, using the convertflow.trackPurchase function.
For example, tracking a purchase with a script on your order confirmation page:
window.addEventListener("cfReady", function(event) {
convertflow.trackPurchase({
revenue: 100.00,
order_id: 'order_983259'
});
});
This function requires a valid revenue numerical value, as well as a unique order_id value.