General
Integrations
How to
Configuration
APIBeta
Track custom events
Panelbear already tracks page views, and other anonymized metrics on your website. However, sometimes you may also need to measure other actions taken by your website visitors over time.
This is where Custom Events come in. You can leverage our fast and private analytics engine to keep track of almost anything you can think of: newsletter sign ups, downloads, form submissions, and plenty more!
Additionally, Panelbear automatically groups all events that fire within a visitor session, and computes conversion rates for you. So for example, if you're sending a Signup
event when a visitor submits the registration form, you could see what percentage of visitors who landed on any page on your website signed up afterwards.
Sending an event
You can already make use of custom events with the default Panelbear installation. No additional steps are necessary besides the basic installation.
To send a custom event, simply call the track
command on your Panelbear script. For example:
panelbear("track", "Signup");
For the example above, a Signup
event will be recorded for the current visitor session. Conversion rates, and other derived metrics are automatically updated for you in real-time.
The track
command takes a second argument, which is the name of the event being tracked. You can name the events however works best for you. But keep in mind that this is the same name that will show up on your dashboards.
Naming custom events
The only restrictions on the event names are:
- Must start with a letter.
- Must only contain letters (
a-z A-Z
), numbers (0-9
), underscores (_
), dashes (-
), or periods (.
). - Cannot exceed 64 characters in length.
Event names are case-sensitive, that means SIGNUP
and signup
will appear as two different entries on your dashboard.
For example, all of the following are valid event names:
panelbear("track", "AppDownload"); panelbear("track", "NewsletterSignup"); panelbear("track", "open.upgrade_modal"); panelbear("track", "checkout-pricing-plans"); panelbear("track", "account.open_settings");
Triggering events on button clicks
It's completely up to you when to trigger the custom events. You could listen for a button click, scroll action, form submission, and pretty much anything you can think of.
<script> let button = document.getElementById("open-upgrade-window"); button.addEventListener("click", function () { panelbear("track", "ViewPlanUpgrade"); }); </script>
Intercepting form submits
Here's an example for sending a Signup
event on a form submit:
<!-- 1) Add an ID to the form --> <form id="signup-form" action="/signup" method="post"> <label for="email">Create your account</label> <input name="email" type="email" /> <button>Sign Up</button> </form> <script> // 2) Listen for form submit document .getElementById("signup-form") .addEventListener("submit", function (e) { e.preventDefault(); // 3) Send Signup event to Panelbear panelbear("track", "Signup"); const form = this; function completeSubmit() { form.submit(); } // 4) Continue form submit after a short delay setTimeout(completeSubmit, 200); }); </script>
A note on personal data
Please ensure you do not include any personally identifiable information (PII) in any event you send to Panelbear. This may include, but is not limited to Name
, Email
, Phone number
, User ID
, and IP address
.
For example, the following are highly discouraged:
// User IDs are personally identifiable information panelbear("track", getUserID()); // Session cookies should never be shared panelbear("track", getCookie("sessionId")); // Query string might contain sensitive data panelbear("track", window.location.search);