JS Event API

2025-07-25 08:35 API Docs

Transfer of user data from the site is carried out with the help of events. The events are sent to Convead as POST requests regardless of whether they are in JS, PHP, or any other language.

Event structure

Format for sending data: POST

Server address: https://tracker.convead.io/watch/event

Query variables:

app_key – app key of the application Convead*
visitor_uid – unique ID of the registered visitor*
guest_uid – unique UID identifier of the guest*
data – JSON data string of the event*

*These fields are mandatory.

Data object format:

Simultaneous transmission of guest_uid/visitor_uid values means that the visitor has moved from “guest” to “registered on the site”. In other cases, one of the values of these parameters has been passed.

If the transmission is successful, the server will respond with 200 OK. If the event is transferred incorrectly, there will be a response with an error code.

Types of events

add_to_cart

Adds one product to the shopping cart.

It is recommended to use update_cart instead of this event.

convead('event', 'add_to_cart', { product_id: '1', qnt: 2, price: 125.03, product_name: 'product', product_url: 'http://site.net/product/1' });

custom

Allows you to send a custom event to capture a specific event, such as a user registration or a request for a feedback form.

convead('event', 'custom', {key: 'event_key'});

The custom event key is set in “My account” > “My events”.

file

Reports the downloading of a file.

convead('event', 'file', {file_url: 'http://example.com/file.zip'}, {});

link

This is automatically called up when the page is opened. For Ajax sites where the transition between pages does not cause the page to reload, it is triggered when you change the URL in the browser address field.

<div class="ql-code-block" data-language="plain">&lt;code&gt;&lt;code&gt;convead('event', 'link', {key_page_id: 123}, {});</div>

mailto

Sends click data to the email address. This expresses the intention of the visitor to send an email.

<div class="ql-code-block" data-language="plain">&lt;code&gt;&lt;code&gt;convead('event', 'mailto', {email: 'chuck-norris@example.com'}, {});</div>

purchase

In the event of a purchase. This is usually sent from the page “Thank you for your order”.

<div class="ql-code-block" data-language="plain">&lt;code&gt;&lt;code&gt;convead('event', 'purchase', { order_id: '12345', revenue: 99.99, items: [ {product_id: '1', qnt: 1, price: 125.15, product_image_url: 'http://site/2.jpg', product_url: 'http://site.net/product/2'}, {product_id: '2', qnt: 15, price: 127.02, product_image_url: 'http://site/2.jpg', product_url: 'http://site.net/product/2'} ]}, { first_name: 'John', last_name: 'Smith', email: 'test@example.net', phone: '555555' } );</div>

update_cart

Transfers the full composition of the cart at that moment. If the cart is cleared, it is sent with an empty items array:

<code><code>convead('event', 'update_cart', { items: [ {product_id: '1', qnt: 1, price: 125.15, product_name: "Product", product_url: 'http://site.net/product/1', product_image_url: 'http://site/2.jpg'}, {product_id: '2', qnt: 15, price: 127.02, product_name: "Product", product_url: 'http://site.net/product/2', product_image_url: 'http://site/2.jpg'} ] });

update_info

Used to transfer the updated data of the visitor into the visitor_info object.

<div class="ql-code-block" data-language="plain">&lt;code&gt;&lt;code&gt;convead('event', 'update_info', {}, {email: 'test@example.net'});</div>

view_product

The product’s views on the product card.

<div class="ql-code-block" data-language="plain">&lt;code&gt;&lt;code&gt;convead('event', 'view_product', { product_id: '123', product_name: 'Product', category_id: '123', product_url: window.location.href, price: 125.15, product_image_url: 'http://site/1.jpg' });</div>

remove_from_cart

Removes the qnt of items from one item in the shopping cart.

It is recommended to use update_cart instead of this event.

<div class="ql-code-block" data-language="plain">&lt;code&gt;&lt;code&gt;convead('event', 'remove_from_cart', { product_id: '1', qnt: 2});</div>