Sending events
How trackbee.track works, the six events you can send, and what the SDK does when a payload is wrong.
trackbee.track(eventType, data);eventType is one of the six names below. data is a plain object of fields for that event.
| Event | Send it when | Required fields |
|---|---|---|
page_view | A page is shown. | none |
product_view | Someone opens a product page. | product_id, variant_id, price |
add_to_cart | Someone adds a product to the cart. | product_id, variant_id, price |
checkout_started | Someone reaches checkout. | line_items |
payment_info_submitted | Someone submits their payment details. | none |
checkout_completed | An order is placed. | order_id |
Send what your storefront can actually produce. There is no requirement to send all six, and nothing is derived from events you skip.
You never pass the visitor, the session, the click ID or the page URL. The SDK attaches all of that itself.
Value rules
These repeat across every event, so they are worth learning once.
| Kind of value | What is accepted | What is rejected |
|---|---|---|
IDs (product_id, variant_id) | A string or a number. '8472019' and 8472019 both work. | null, objects, arrays |
Prices (price, subtotal_price, total_price, discount_amount, final_line_price) | A non-negative number, or a string of digits with an optional decimal part: 29.99, '29.99', '30', 0 | '29,99', 'EUR 29.99', '$29.99', '', -1 |
Quantities (quantity) | A whole number of at least 1 | 0, -1, 1.5, '2' |
order_id | A whole number up to 9007199254740991, or a string of digits | 'ORD-1024', -5, 10.5 |
Flags (is_first_order) | true or false | 'true', 1, 'yes' |
| Everything else | A string | numbers, booleans |
Prices travel as you write them. Use the minor-unit decimal format the store sells in, like '29.99', and pass the currency alongside it.
What happens when a payload is wrong
The SDK never throws into your code. Everything below is reported through the console instead.
A required field is missing
The whole event is dropped and you get:
[TrackBee] track("product_view") did not send the event. Missing required fields: variant_id, priceA value is the wrong type
Also dropped, with the field, what was expected, and what you passed:
[TrackBee] track("product_view") did not send the event. Invalid fields: price must be a non-negative number, or a string like "9.99", got "29,99"Problems inside a list name the position:
[TrackBee] track("checkout_started") did not send the event. Invalid fields: line_items[1].quantity must be a whole number of at least 1, got 0The event name is wrong
Nothing is sent, and you get a warning rather than an error:
[TrackBee] Unknown event type: "purchase". Known events: page_view, product_view, add_to_cart, checkout_started, payment_info_submitted, checkout_completedA field name is wrong
Misspelled fields disappear silently
Fields the event does not recognize are dropped with no message at all. Write qty instead of quantity and the event still sends, without the quantity. Check your field names against the page for that event.
A value is null or undefined
Treated as if you had not passed the field. Required means the event is dropped; optional means it is skipped. Both are fine to pass, so you do not need to strip empty values yourself.
Calls never throw
track() is wrapped so that an error inside the SDK is logged and stops there. It will not break the code that called it, and it will not stop the next event from going out.