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.
الأدلة متوفرة باللغة الإنجليزية.
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.contloWebSDKexists before you use it. - The methods authenticate with the public key that is already in your snippet. You do not pass a key yourself.
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.
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
)window.contloWebSDK.sendUserData(
'ada@example.com',
'+14155550123',
'Ada',
'Lovelace',
{ loyalty_tier: 'gold', preferred_category: 'running' },
false
);| Argument | Notes |
|---|---|
email, phone_number | Send 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_name | Optional. |
custom_properties | Any extra facts about the contact, as a flat object. They appear as contact properties in Contlo. See Custom properties and tags. |
is_profile_update | Marks 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.
<script>
window.cntl_events = window.cntl_events || [];
window.cntl_events.push(['user_identify', { email: 'ada@example.com' }]);
</script>Track a custom event
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
)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_typeandsdk_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.
| Method | What 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. |
// 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.
| Method | Use 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. |
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_casefor event names and property keys:wishlist_item_added, notWishlist 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_addedwith aproduct_idis better than a separate event per product. - Keep the type of a property stable. If
priceis 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 key | Name in the app | Recorded when |
|---|---|---|
view_page | Viewed Page | A recognized visitor views a page that is not a product page. |
view_product_page | Viewed Product | A recognized visitor views a product page. |
added_to_cart | Added To Cart | A product is added to the cart. |
checkout_started | Checkout Started | The shopper starts checkout. |
order_created | Placed Order | An order is created. One per order. |
ordered_product | Ordered Product | A product is ordered. One per product in the order. |
order_fulfilled | Fulfilled Order | The order is fulfilled. |
order_in_transit | Order In Transit | The order is in transit. |
order_delivered | Delivered Order | The order is delivered. |
order_cancelled | Cancelled Order | The shopper cancels an order. |
customer_activity | Active On Site | The 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
Build a segment from contacts who did, or did not do, an event. Your own events are listed under Custom Events in the condition picker.
Start an automation the moment an event arrives, and use its properties in the message.
Chart event volume over time under Analytics → Events.
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 see | Cause and fix |
|---|---|
Cannot read properties of undefined on window.contloWebSDK | The 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 console | The first argument of sendEvent was missing. |
Error: 400 in the console | The 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 console | The 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 contact | A previous shopper's identity is still saved in the browser. Call userLogout when a shopper signs out. |
أدلة ذات صلة
- Install web trackingAdd the Contlo tracking snippet to a custom site, see what it records automatically, verify the install and review the cookies it sets.
- REST APISend contacts and events to Contlo from your server: authentication, the identify and track endpoints, request and response examples, limits and errors.
- Mobile SDKsAdd Contlo to an Android, iOS, React Native or Expo app: install, initialize, identify users, track events and set up push notifications.
- SegmentsGroup contacts by who they are and what they did, using properties, events, orders and lists, then send to them.
- Automation triggers and actions referenceEvery trigger, filter, condition, message block and flow action in the automation builder, with what each one does and its options.