Skip to content
Contlo by QuestionPro
Browse documentation

Track events and identify visitors

Once the tracking snippet is on your site, two objects are available in the browser: window.contloWebSDK and window.contlo. Use them to attach an email or phone number to the current visitor and to record what they do, such as starting a quiz, adding to a wishlist or booking a demo. Every event you send can trigger an automation or define a segment, which is how browsing turns into first orders and repeat purchases.

Browser JavaScriptUses your public API keyEvents feed segments and automations

Before you start

  • Install the tracking snippet first. See Install web tracking. Shopify and WooCommerce stores already have it.
  • The snippet loads asynchronously. Call the methods after the page has loaded, or check that window.contloWebSDK exists before you use it.
  • The methods authenticate with the public key that is already in your snippet. You do not pass a key yourself.
Wait for the snippet
function whenContloReady(callback) {
  if (window.contloWebSDK) return callback();
  window.addEventListener('load', function () {
    if (window.contloWebSDK) callback();
  });
}

Identify a visitor

Identifying a visitor creates or updates a contact in Contlo and links this browser to it. Do it wherever you learn who the shopper is: sign-up, login, checkout, a newsletter form of your own.

Signature
window.contloWebSDK.sendUserData(
  email,              // string or null
  phone_number,       // string or null, with country code
  first_name,         // string or null
  last_name,          // string or null
  custom_properties,  // object or null
  is_profile_update   // boolean
)
Example
window.contloWebSDK.sendUserData(
  'ada@example.com',
  '+14155550123',
  'Ada',
  'Lovelace',
  { loyalty_tier: 'gold', preferred_category: 'running' },
  false
);
ArgumentNotes
email, phone_numberSend at least one. If you pass null or an empty string, the SDK reuses the email or phone it saved from an earlier call or form submission in this browser.
first_name, last_nameOptional.
custom_propertiesAny extra facts about the contact, as a flat object. They appear as contact properties in Contlo. See Custom properties and tags.
is_profile_updateMarks the call as an update to a contact that already exists. Pass false when in doubt.

After a successful call, the email and phone are saved in cookies on your domain, so later events from the same browser are tied to this contact without you passing them again.

Identify a logged-in shopper at page load

If your server already knows the shopper when it renders the page, you can hand the email to the snippet before it starts. Put this above the snippet. Contlo then recognizes the visitor on that page view.

HTML
<script>
  window.cntl_events = window.cntl_events || [];
  window.cntl_events.push(['user_identify', { email: 'ada@example.com' }]);
</script>

Track a custom event

Signature
window.contloWebSDK.sendEvent(
  event_name,          // string, required
  email,               // string or null
  phone_number,        // string or null
  profile_properties,  // pass null (see note below)
  event_properties     // object
)
Example
window.contloWebSDK.sendEvent(
  'wishlist_item_added',
  null,   // reuse the identified email
  null,   // reuse the identified phone
  null,
  {
    product_id: 'SKU-1042',
    product_name: 'Trail Runner 2',
    price: 129.0,
    currency: 'USD'
  }
);
  • An event must belong to a contact. If the visitor has not been identified in this browser and you pass no email or phone, the event is rejected.
  • The SDK adds a few properties to every event on its own: source (Web), os_type and sdk_version, plus the browser, current page URL and time zone.
  • Leave out property keys that have no value instead of sending null.

Login and logout

Two helpers record sign-in and sign-out and keep the saved identity in step with your own session.

MethodWhat it does
window.contloWebSDK.userLogin(email, phone_number, properties)Saves the email and phone for this browser and records a user_logged_in event with the properties you pass.
window.contloWebSDK.userLogout(email, phone_number, properties)Records a user_logged_out event, then removes the saved email and phone from this browser. Call it on shared devices so the next shopper's activity is not credited to the previous one.
Example
// After your own login succeeds
window.contloWebSDK.userLogin('ada@example.com', '+14155550123', { method: 'password' });

// When the shopper signs out
window.contloWebSDK.userLogout(null, null, {});

The window.contlo methods

window.contlo is a second set of methods that take callbacks or return a promise, which is useful when you need to know the result before moving on, for example before redirecting after a form submit.

MethodUse it to
sendEvent(event_name, email, phone_number, properties, success_callback, failure_callback)Record an event for a contact by email or phone.
sendEventWithProfileProperties(event_name, email, phone_number, profile_properties, properties, success_callback, failure_callback)Record an event and update contact properties in the same call.
sendEventWithCustomerId(event_name, customer_id, properties, success_callback, failure_callback)Record an event for a contact by their store customer ID.
sendAsyncEvent(event_name, email, phone_number, properties)Same as sendEvent, but returns a promise. Throws Both email and phone number cannot be empty. if you pass neither.
Example
try {
  await window.contlo.sendAsyncEvent(
    'demo_booked',
    'ada@example.com',
    null,
    { plan: 'growth', seats: 5 }
  );
  window.location.href = '/thank-you';
} catch (error) {
  console.error('Contlo event failed', error);
}

Naming events and properties

  • Use lowercase snake_case for event names and property keys: wishlist_item_added, not Wishlist Item Added. The built-in events follow this pattern, and the mobile SDKs replace spaces with underscores.
  • Name events as something that happened, object first: quiz_completed, demo_booked, subscription_paused.
  • Keep one event per action and put the detail in properties. wishlist_item_added with a product_id is better than a separate event per product.
  • Keep the type of a property stable. If price is a number once, send a number every time.
  • Send phone numbers with a plus sign and country code, such as +14155550123. Numbers without a country code can be read as belonging to the wrong country.
  • Do not put secrets, passwords or full payment details in properties.

Events Contlo records for you

You do not need to send these. Contlo records them from your store connection and from the tracking snippet. Pick different names for your own events so the two never get mixed up.

Event keyName in the appRecorded when
view_pageViewed PageA recognized visitor views a page that is not a product page.
view_product_pageViewed ProductA recognized visitor views a product page.
added_to_cartAdded To CartA product is added to the cart.
checkout_startedCheckout StartedThe shopper starts checkout.
order_createdPlaced OrderAn order is created. One per order.
ordered_productOrdered ProductA product is ordered. One per product in the order.
order_fulfilledFulfilled OrderThe order is fulfilled.
order_in_transitOrder In TransitThe order is in transit.
order_deliveredDelivered OrderThe order is delivered.
order_cancelledCancelled OrderThe shopper cancels an order.
customer_activityActive On SiteThe contact is active on your site.

Order events come from your store connection, so which of them you see depends on your platform. See Connect your store.

Where your events show up

If you do not see Analytics → Events, it is not enabled for your account yet. Ask your account manager or write to hello@contlo.com.

Troubleshooting

What you seeCause and fix
Cannot read properties of undefined on window.contloWebSDKThe snippet has not loaded yet, or is blocked. Wait for the page load event and check the network tab for the script request.
Event name cannot be empty! in the consoleThe first argument of sendEvent was missing.
Error: 400 in the consoleThe event had no email or phone and the visitor is not identified in this browser. Identify the visitor first, or pass the email or phone with the event.
Error: 403 in the consoleThe call came from a site where the snippet has not registered. Send events from the same origin the snippet runs on.
Please whitelist the schema before sending events..You used a window.contlo method with an event that is not set up for your account. See the note in The window.contlo methods.
Invalid key value for … as per schema.A property was sent with the wrong type, for example text where a number is expected.
Events arrive under the wrong contactA previous shopper's identity is still saved in the browser. Call userLogout when a shopper signs out.

Related guides

Can't find something? Email us