JavaScript API

convertflow.identify(data, callback)

Attaches an email or phone plus profile and custom fields to the current visitor for identity resolution. Also pre-fills form fields and personalizes merge tags. Preset fields: email, phone, name, last_name, company_name, company_title, url, state, city, country, zip_code, address. Anything under custom_fields is stored as a custom field by slug. Re-runs campaign targeting once the library is ready.

convertflow.identify({
  email: '[email protected]',
  name: 'Jane',
  custom_fields: { plan: 'pro' }
}, function () {
  console.log('identified');
});

convertflow.load({ cta_id, callback })

Loads a campaign into the page without displaying it, so a later trigger can show it instantly. Injects a hidden embed container for the campaign.

convertflow.load({ cta_id: 12345 });

convertflow.trigger({ cta_id, step })

Displays a campaign you already loaded. Pass step (a step position) to jump the visitor's variant to that step.

convertflow.trigger({ cta_id: 12345, step: 2 });

convertflow.start()

Resets all campaigns, then re-runs visitor tracking and targeting conditions. Call it after a client-side navigation, or after you change data that targeting depends on.

convertflow.start();

convertflow.close({ cta_id, track })

Closes visible popup, hook, sticky bar, and two-tap campaigns. With no argument, it closes all of them. Pass cta_id to close one, and track: true to record the close.

convertflow.close({ cta_id: 12345 });

convertflow.trackPurchase({ revenue, order_id, currency }) since 2.2

Records a purchase (order conversion) for the current visitor, once per session per order. revenue is a number in major units, and order_id is a string or number of 1 to 100 characters. Not available on earlier library versions.

convertflow.trackPurchase({
  revenue: 49.99,
  order_id: 'ORDER-1001',
  currency: 'USD'
});

convertflow.validations({ fieldKey: fn })

Registers custom form-field validators, keyed by field slug. Each function receives the field value and returns true when the value is valid, or an error message string to block submission.

convertflow.validations({
  vat_number: function (value) {
    return /^[A-Z]{2}\d{8,12}$/.test(value) || 'Enter a valid VAT number';
  }
});

convertflow.person object

The current visitor or contact profile: visitor_token, contact fields (email, phone, name, and so on), custom fields under extra, and tracking data. It populates asynchronously, so it stays undefined until the cfReady event fires.

convertflow.cart object

Live Shopify cart snapshot: { value, count } (value in major units). On the 2.2 library it also tracks orders by order id. Shopify stores only.

convertflow.product object

The Shopify product of the current product page: { id, title, type, price, compare_at_price, description }. Shopify stores only.

convertflow.session since 2.2 object

The visitor's current session: page count, visited urls with timestamps, UTM attribution, and a newSession flag. It's empty until the library initializes session tracking.

convertflow.events array

Append-only log of every ConvertFlow event fired on this page view, in order. Each entry is the same payload handed to event listeners.

convertflow.ctas object

Registry of loaded campaigns, keyed by campaign id. Advanced: it's mostly useful for inspecting which campaigns the library has loaded.

cfReady

The library finished loading the visitor and running targeting. convertflow.person is available from this point on. No payload.

window.addEventListener('cfReady', function () {
  console.log(convertflow.person);
});

cfView

A campaign or step was displayed to the visitor.

cfSubmit

A form, survey, or quiz was submitted. The payload's fields object carries the submitted values.

window.addEventListener('cfSubmit', function (e) {
  console.log(e.detail.cta, e.detail.fields);
});

cfConversion

A visitor converted on a campaign button or element.

cfCompletion

A visitor completed a campaign by reaching its completion step or action.

cfClose

A campaign was closed. The payload carries the campaign and variant only, with no step or element.

cfAddToCart

A product was added to the cart through a ConvertFlow products element. The payload includes product details.

cfAnswer since 2.2

A quiz question was answered. It fires for every question, including the last one. The payload's fields.extra object maps question slugs to answers.