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 automagically 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.

Custom events

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);