Chapter 04

Custom event tag: a simple tag for collecting more data

By Anna Tomalik

In chapter 2, we explained that tags are pieces of code that can do different things. Well, they can do almost anything. There is an infinite number of tags that can be used, so we can’t review them all. But in this chapter, we’ll show you a common custom event tag.

A custom event tag is used for collecting event data for Analytics. By default, Analytics collects lots of events like page views, outlinks or downloads. But sometimes you may want to record additional events like button clicks, form submissions or page scrolling. This is when you reach for a custom event tag.

A custom event tag records an event after being triggered and passes event information to Analytics. That information comes in a structure consisting of:

  • Category (required)
  • Action (required)
  • Name (optional)
  • Value (optional)
Custom event structure in Piwik PRO

Let’s try to create a custom event tag that will collect data about clicks on a sign-up button.

To create a custom event tag, follow these steps:

  1. Go to Menu > Tag Manager.
  2. Navigate to Tags.
  3. Click Add a tag.
  4. Name the tag and select the following type: Custom event.
  5. Click Next.
  6. Now we need to set up how the information about our event will be passed. We’ll do it this way:
    • Category: Button
    • Action: Sign up
    • Name: {{ Page Path }}
    Custom event in Piwik PRO

    Tip: We use a built-in variable {{ Page Path }} that holds information about the page path of the page URL on which the event occurred. It’ll show us where the sign-up button was clicked.

  7. In Advanced tag settings, choose Consent type. Set it up if you use a consent form on your site. This tag will fire only for visitors who accept the selected consent type.
  8. In Tag triggers, click Add a trigger.
  9. Name the trigger and select the following trigger: Click.

    Note: A click trigger fires a tag on all clicks by default, but you can use conditions to define a certain click as a trigger.

  10. In Event conditions, choose When conditions are met.
  11. We’ll set the following conditions:
    • Click Classes equals et_pb_button et_pb_button_0 et_pb_bg_layout_light
    • Page URL equals
    Custom event in Piwik PRO

    Note: We use a click class (et_pb_button et_pb_button_0 et_pb_bg_layout_light) to define the clicked element and add a condition checking that the click occurs on our home page. This setup is unique for our site, and yours can be different. For more on how to find click classes and track buttons, see our guide.

  12. Click Save for the trigger.
  13. Click Save for the tag.
  14. Click Debug.
  15. Turn on Prevent page reload. This option will help us test clicks because it won’t redirect us to the clicked page URL.
    Debug mode in Piwik PRO
  16. Now, we’ll click on a sign-up button and check if our custom event tag was fired.
    Debug mode in Piwik PRO
  17. Click on your custom event tag to see tag details.
    Debug mode in Piwik PRO
  18. In the detailed view, you’ll see the full code that is responsible for collecting this custom event:
    <script type="text/javascript">
        	var _paq = _paq || [];
           	 _paq.push(['trackEvent', 'Button', 'Sign up', {{ Page Path }}]);

    Tip: You can use a similar code in a custom code tag. But generally it’s easier to use a custom event tag to track events.

  19. When you’re happy with how the tag works, click Publish.
  20. You can quickly check if data is being collected correctly by going to Menu > Analytics > Settings > Tracker debugger.

    Note: Data in the tracker debugger appears instantly. Data in reports appears in about 30 minutes.

  21. Now your data is collected, and you can see it under Menu > Analytics > Reports > Custom events.
    Custom event report in Piwik PRO
  22. You can also see custom events under Analytics > Reports > Session log.
    Session log report in Piwik PRO

    Tip: See our guide for advanced analytics for more examples of using a custom event tag.

For developers: You can set up custom events manually by modifying the tracking code.