How to track custom events with Pieowl

Custom events are the base of product analytics. They record specific actions, like button clicks, form submits, video plays and purchases. This guide shows you how to track custom events in Pieowl on different platforms.

Every Pieowl SDK uses the same API for event tracking. Learn the pattern once and you can use it anywhere.

Prerequisites

• A Pieowl account (start a 14-day free trial)
• The Pieowl script or SDK installed in your project
• Your Client ID from the dashboard

Understand event structure

Every event has two parts: a name and optional properties. The name says what happened. The properties add context: how, where and to what.

A good event name reads like a short sentence in the past tense. Instead of "click" or "button", use names like signup_button_clicked or purchase_completed. Then your dashboard makes sense at a glance.

For property names, pick one style and stick to it. If one event has button_name, use button_name on similar events too, not buttonName or name.

Track simple events

The simplest event is a name with no properties. That works when the context is obvious, like a button that only appears in one place.

With the Web SDK from npm, import your Pieowl instance and call track.

import { pieowl } from './pieowl';

pieowl.track('signup_button_clicked');

With the script tag, call the global window.pieowl function with 'track' as the first argument.

<button onclick="window.pieowl('track', 'signup_button_clicked')">
  Sign Up
</button>

On the server, the JavaScript SDK works the same way.

import { pieowl } from './pieowl';

pieowl.track('order_placed');

track sends the event in the background and returns a promise. You don't need to wait for it, so it won't hold up your code.

Track events with properties

Properties turn raw events into useful data. Instead of only knowing that someone clicked a button, you know which button, where it was and what the user was doing.

Pass properties as the second argument to track. Add any context that will help you filter and compare later.

import { pieowl } from './pieowl';

pieowl.track('button_clicked', {
  button_name: 'signup',
  button_location: 'hero_section',
  page: 'homepage',
});

With the script tag, pass the properties object as the third argument.

<button onclick="window.pieowl('track', 'button_clicked', {button_name: 'signup', button_location: 'hero_section'})">
  Sign Up
</button>

Choose your properties with care. Track the data that answers real questions, like which signup button works best or which page drives the most sign-ups.

Here is a purchase event with useful properties.

pieowl.track('purchase_completed', {
  product_id: 'prod_123',
  product_name: 'Premium Plan',
  amount: 99.99,
  currency: 'USD',
  payment_method: 'credit_card',
  previous_plan: 'free',
});

To see revenue in the dashboard's revenue reports, use the purchase method instead. The e-commerce guide shows how.

Never put sensitive data in event properties. Passwords, card numbers and other personal data don't belong in your analytics.

Use data attributes

On buttons and links, you can track clicks with a data-track attribute. This works well when you want tracking without writing JavaScript.

Set data-track to the event name. Add more data-* attributes for properties.

<button
  data-track="button_clicked"
  data-button-name="signup"
  data-button-location="hero_section"
>
  Sign Up
</button>

The SDK turns the attribute names into camelCase. So data-button-name arrives as buttonName in your event data. Attribute values are always sent as text.

Data attributes need Clicks you marked in your code to be on in Settings → Site → What Pieowl counts. It is on by default. If clicks don't show up, check that this switch is on.

Common event patterns

For form submits, track the submit plus some context about the form.

function handleSubmit(event) {
  event.preventDefault();

  pieowl.track('form_submitted', {
    form_name: 'contact',
    form_location: 'footer',
    fields_completed: 3,
  });

  // Submit the form
}

For videos, track play and completion with timing data.

function handleVideoPlay(video) {
  pieowl.track('video_played', {
    video_id: video.id,
    video_title: video.title,
    video_duration: video.duration,
  });
}

function handleVideoComplete(video) {
  pieowl.track('video_completed', {
    video_id: video.id,
    watch_time: video.currentTime,
  });
}

For search, include the query and the number of results. That shows you what users are looking for.

function handleSearch(query, results) {
  pieowl.track('search_performed', {
    query: query,
    query_length: query.length,
    results_count: results.length,
    has_results: results.length > 0,
  });
}

Verify your setup

After you add event tracking, open the Pieowl dashboard and go to the realtime view. Trigger the events in your app and check that they show up within a few seconds.

No events? Check that your Client ID is correct and that the SDK started without errors. Your browser's developer tools show whether tracking requests are sent. Look for requests to api.pieowl.com.

Next steps

Now that you track custom events, you can identify users to link events to real people. To analyze your events, the funnel guide shows you how to measure conversion rates across multi-step flows. The SDK documentation covers more features, like global properties and event filters.

For framework examples and setup steps, see:

• Next.js analytics guide for Next.js apps
• React analytics guide for React apps
• Node.js analytics guide for server-side tracking
• Python analytics guide for Python apps, using the HTTP API