Custom events

Sending an event

pear.track('signup')

With properties:

pear.track('signup', { plan: 'pro', source: 'pricing-page' })

The global is available as soon as the script has loaded. If you call it from code that might run first, guard it. A missing global should never break your page over an analytics call:

window.pear?.track('signup', { plan: 'pro' })

Naming

Lowercase, no spaces, present tense, and the same name everywhere. The names show up in a dropdown when you pick conversions, and a list containing signup, sign_up and Signup is a list somebody will pick the wrong one from.

Name the thing that happened, not where it happened. signup is useful across every page; homepage_hero_button is a name you will regret when the button moves.

Properties

Strings and numbers. Keep them low-cardinality and keep them non-personal.

Do not put personal data in an event property. This is the one place the architecture cannot stop you: everything else about the collection is incapable of holding an email address, and pear.track would happily accept one. Putting it there turns a database with no personal data in it into a database with personal data in it, and every claim on the privacy page stops being true for you.

Order value, plan name, item count, form name: fine. Email, customer ID, full name, postcode, free-text form contents: not fine.

Revenue

Two property names are treated specially, so ROAS and revenue-per-session can be computed:

pear.track('purchase', { value: 149.0, currency: 'USD', items: 3 })

Making an event a conversion

Marketing → Settings → Conversion events, then pick from the observed names.

Pick, do not type. A conversion event name that matches nothing produces a null CPA across the whole table with no error message anywhere, and because the rest of the table still fills in, it is easy to read the blanks as “no conversions yet” rather than as a typo.

More than one event can count. Selecting both signup and purchase means the conversion column is the sum, and CPA is spend divided by that sum. That is usually not what you want: two different things costing different amounts, averaged into one number. Prefer one.

Server-side events

Events that happen after the browser is gone (a subscription renewing, a lead qualifying in a CRM) can be posted directly. Without a session to attach to, they arrive unattributed, which makes them useful as totals but useless for CPA by campaign.

curl -X POST https://metrics.example.com/api/send \
  -H 'Content-Type: application/json' \
  -d '{
    "type": "event",
    "payload": {
      "website": "b6c9e2a1-4f3d-4a02-9f77-1c5b0d8e2a44",
      "hostname": "example.com",
      "url": "/renewal",
      "name": "renewal",
      "data": { "value": 79, "currency": "USD" }
    }
  }'

Checking events arrive

Fire one, then look at Events in the dashboard. New names appear within a few seconds and become selectable as conversions immediately.

If an event is not there, check the browser console for a failed request and confirm the website ID matches. See Install.