Custom events

When you finish, your event appears in Events with a stable name and the properties a conversion rule needs.

What the SDK tracks without you

The web SDK sends a pageview on load and on every SPA route change. That’s the whole list. Clicks, scrolls, form submits, outbound links, and errors are yours to send, so call track() for each one.

Name the event

Use one lowercase, stable name per action. Put the variation in properties.

datalyr.track('signup_completed', {
  plan: 'pro',
  billing_period: 'annual'
})

Never put an ID, a price, or any other changing value in the event name. A name such as purchase_ord_4821 creates a new event name per order, and no conversion rule can match it.

Reserved names

Datalyr sends these names itself. Passing one to track() corrupts the data behind that feature.

Reserved name	Datalyr sends it for
`$identify`	`identify()`
`$alias`	`alias()`
`$group`	`group()`
`$app_download_click`	`trackAppDownloadClick()` and an app tracking link
`$link_click`	A tracking-link redirect
`$web_attribution_matched`	A web-to-app match by IP address
`$web_attribution_merged`	A web-to-app match by email address
`$set`	A user-properties update
`pageview`	Automatic and manual page tracking

Every name starting with $ is reserved. Never send one.

Properties a revenue event needs

A conversion rule reads these four properties. Send all four on any purchase-like event.

Property	Type	Why
`value`	Number	The amount. Send `79`, never `"79"` or `"$79"`.
`currency`	String	An ISO 4217 code, such as `USD`.
`order_id`	String	The destination deduplicates on it.
`email`	String	Feeds hashed advanced matching at the destination.

datalyr.track('order_completed', {
  order_id: 'ord_4821',
  value: 79,
  currency: 'USD',
  email: '[email protected]'
})

Keep a property’s type stable. A property that’s a number one day and a string the next breaks the sum in Reports.

Limits

Limit	Value	Over the limit
Request body to `/`	1 MB	HTTP `413`
Request body to `/track`	256,000 bytes	HTTP `413`
Events per workspace per minute	10,000	HTTP `429`, `Retry-After: 60`
`Content-Type`	Must match `application/json`	HTTP `415`

Datalyr enforces no event-name length limit, no property count limit, and no per-property size limit. Datalyr drops an event that has no workspace ID, event name, event ID, or visitor_id. A request returns 400 only when every event in it is invalid.

Never send a password, an access token, a full card number, or regulated health data in a property. We store every property you send and forward matched ones to your ad platforms, so a secret in a property leaves your control.

Verify

Deploy to a staging environment.
Perform the action once as a known test user.
Open Events.
Filter by your event name.
Confirm the row shows the right distinct id, timestamp, and properties.

Build the conversion rule only after this row is correct.

When it does not work

Symptom	Cause	Fix
The event never appears	You called `track()` before `init()`.	Await `datalyr.ready()`, then call `track()`.
The event appears with no properties	You passed a second argument that is not an object.	Pass a plain object.
The event fires several times per action	A React component re-renders and calls `track()` in the render body.	Move the call into an event handler or an effect.
`Reports` sums the value as zero	`value` arrives as a string.	Send a number.
HTTP `429` in the console	You passed 10,000 events in one minute.	Batch, or reduce the event.

Web SDK: the full track() signature and every config option.
Conversion delivery: forward the event to an ad platform.
Identity: attach the event to a known user.

Get started

Installation

Revenue

Using Datalyr

Advanced

Integrations

Account & billing

Troubleshooting

What the SDK tracks without you

Name the event

Reserved names

Properties a revenue event needs

Limits

Verify

When it does not work

Next

​What the SDK tracks without you

​Name the event

​Reserved names

​Properties a revenue event needs

​Limits

​Verify

​When it does not work

​Next

What the SDK tracks without you

Name the event

Reserved names

Properties a revenue event needs

Limits

Verify

When it does not work

Next