How to track custom events on your website

Pageviews tell you people arrived. They do not tell you whether anyone clicked the pricing button, or which plan they picked.

Those actions are custom events. You name them. Sitebase stores them next to pageviews and form submissions.

Sitebase’s Events page is that log. Feature embeds write their own events. Your buttons and scripts can write the rest.

Sitebase is in private beta. Public signup isn’t open. These steps are for accounts with access.

Enable Events and put the snippet on every page

Add your website in Sitebase. On the Features to start with step, keep Events checked under Data. It is on by default. If the site already exists, use + Add more and enable Events.

Open Events in the sidebar. Until something arrives, the page itself explains how events get in. There is no Setup tab. Events use the same script as Analytics.

Copy the site-level snippet from that empty Events page, or from Analytics. Put it in the shared layout so it loads on every public page.

<script
  async
  crossorigin="anonymous"
  src="https://sitebase.dev/embed.js"
  data-sitebase-site="YOUR_SITE_KEY"
></script>

Replace YOUR_SITE_KEY with the website key from your dashboard. The attribute is data-sitebase-site, not data-sitebase-widget. A feature embed on the same page also starts the tracker, so you do not need both on a contact page. You still want the site snippet on pages that have no feature.

In an Astro layout, add is:inline so the script stays intact.

Pick one action you can check

Start with one click you can perform yourself.

A pricing page button labeled “Start with Pro” is a good first event. Name it signup_click. You will press that button on the published site and look for that name in the log.

If the click already submits a Sitebase waiting list or contact form, skip the custom event. Those already write waitlist_signup or contact_message. Custom events are for actions the product does not record on its own.

Mark the button

The simplest path is an HTML attribute. Add data-sitebase-event to the button or link. A click on that element, or on anything inside it, sends the name.

<a href="/checkout" data-sitebase-event="signup_click">Start with Pro</a>

This path sends the name only. It does not attach properties.

If you need a property, call sitebase.track from your own code. The second argument is optional.

sitebase.track('signup_click', { plan: 'pro' })

plan is a string. You can also send a number or a boolean. Up to 10 properties per event. Strings longer than 200 characters are trimmed. Extra keys are dropped. The event still records.

If your click handler can run before embed.js loads, queue early calls with this stub above your code:

<script>window.sitebase=window.sitebase||{q:[],track:function(){this.q.push(arguments)}};</script>

Event names can be up to 60 characters. Use letters, numbers, spaces, and _ . : -. Do not send pageview. That name is reserved for the tracker.

Check the published page

The tracker ignores localhost and file: pages. Publish the site, then open the public URL in a fresh window.

Click the button. Open Events in Sitebase. The first event should land within a few seconds. After that, Data is the default tab and the how-to moves to Docs.

You should see signup_click in the log. Each row shows the name, the time, the page path, country, browser, and a short visitor id. If you sent { plan: 'pro' }, that pair appears on the row. Filter to signup_click to open the Properties card with the most common plan values.

The range tabs are Today, 7 days, and 30 days. The per-day chart starts at 7 days.

If nothing appears, open the Network panel. Confirm embed.js loaded, then look for a request to /v1/event. A content blocker can swallow both. Test once in a clean browser profile. If that browser has localStorage.sitebase_ignore set to "true", clear it.

What already lands without extra code

Pageviews from the snippet show up as pageview. A waiting list signup writes waitlist_signup. A contact form writes contact_message. Newsletter signups, lead magnet requests, and testimonials have their own names too.

Use those when they answer the question. Add a custom event when they do not.

Visitor ids are anonymous hashes that rotate every day. You can follow a short path on one day. You cannot follow the same person tomorrow. Raw event rows are kept for 6 months.

If you later want the path from /pricing to signup_click to a waiting list join, Sitebase can build that as a funnel. You need the events first.

For the reports around pageviews, see the analytics guide. For install detail, see the events documentation.