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 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.

cfSubmit - Fires only when CTA form and survey elements have been submitted.

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(CTA_ID) - Loads a CTA based on the given CTA_ID value. [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.identify(payload) - Identifies the current visitor with the email address in the payload. [See example]

How to load popup and sticky bar CTAs

Once ConvertFlow's script has finished loading, you can load a specific CTA onto the page by calling  convertflow.load(CTA_ID)

jQuery(document).on('cfReady', function(event) {
    // load a popup CTA by replacing CTA_ID with ID found in CTA's dashboard URL
    convertflow.load(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.

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.

jQuery(document).on('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 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  identify function.

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 ConvertFlow to identify someone only 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.

jQuery(document).on('cfReady', function(event) {
    convertflow.identify({email: 'EMAIL_ADDRESS_HERE', override: true}); 
});

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