Set up events

What are events?

Trustlytics counts page views automatically. Meaning you see right away which pages of your website were visited.

But what happens on a page? Which button gets clicked, which form submitted, which plan selected? You only know that if you mark it yourself.

That is exactly what events are for. You put a small marker on an element of your website, and from that moment on Trustlytics counts every click on it.

Where to start? Take the actions that money or time hangs on for you. So: the buy button, the contact form, a click on your phone number, a download, and an appointment booking. What you do not have to mark is your navigation, because which page somebody opens next is something you see in the page views anyway.

Before we start: you choose the names yourself

In the examples below you read words like Newsletter signup, Plan selected, plan, billing, starter, pro. Those are examples. None of them is fixed.

Two things you decide yourself:

• The event name (that goes after data-trustlytics-event="...")
• The properties (if you need any)

Trustlytics stores exactly what you write. There is no list you have to pick from. Completely free.

The four attributes at a glance

So you keep track: there are exactly four attributes. One is required, three are optional.

For most cases you only need the first one. The other three come in when you want to know more.

Example 1: counting a newsletter signup

Here is what a normal newsletter form looks like:

<form action="/newsletter" method="POST">
 <input type="email" name="email" required>
 <button type="submit">Sign up</button>
</form>

You add exactly one detail:

<form action="/newsletter" method="POST" data-trustlytics-event="Newsletter signup">
 <input type="email" name="email" required>
 <button type="submit">Sign up</button>
</form>

Done. From now on the event "Newsletter signup" appears in your Trustlytics report every time somebody submits the form.

Instead of "Newsletter signup" you can write whatever you want. "Signup newsletter", "Signed up for newsletter", "Newsletter subscribe". Whatever makes sense to you is right.

Example 2: counting a button click

You have a "Book a demo" button:

<a href="https://calendly.com/your-company">Book a demo</a>

The marker for it:

<a href="https://calendly.com/your-company" data-trustlytics-event="Demo booked">Book a demo</a>

And that is it. Again: "Demo booked" can be replaced with "Demo requested", "Calendly opened", "Appointment requested". Take whatever makes sense to you.

Example 3: when you want to store extra details

Sometimes "Plan selected" is not enough. You want to know which plan got clicked. That is what properties are for (the data-trustlytics-event-property-... attribute).

Instead of creating three separate events ("Starter clicked", "Pro clicked", "Enterprise clicked"), you use one event with a property:

<a href="/checkout?plan=starter"
 data-trustlytics-event="Plan selected" 
 data-trustlytics-event-property-plan="starter">Starter</a>
<a href="/checkout?plan=pro"
 data-trustlytics-event="Plan selected"
 data-trustlytics-event-property-plan="pro">Pro</a>
<a href="/checkout?plan=enterprise"
 data-trustlytics-event="Plan selected"
 data-trustlytics-event-property-plan="enterprise">Enterprise</a>

In your Trustlytics report you then see, under the event "Plan selected":

• plan: starter (40%)
• plan: pro (50%)
• plan: enterprise (10%)

That way you see immediately which plan pulls best. Without having to maintain three events.

The property is called "plan" because we wrote "plan". These would work just as well:

data-trustlytics-event-property-package="starter"
data-trustlytics-event-property-tier="starter"
data-trustlytics-event-property-type="starter"

Whatever comes after data-trustlytics-event-property- is your name for the property. That exact name shows up in the report later.

Example 4: combining several properties

You want to count the plan and the billing mode:

<a href="/checkout?plan=pro&billing=monthly"
 data-trustlytics-event="Plan selected"
 data-trustlytics-event-property-plan="pro"
 data-trustlytics-event-property-billing="monthly">Pro (monthly)</a>
<a href="/checkout?plan=pro&billing=yearly"
 data-trustlytics-event="Plan selected"
 data-trustlytics-event-property-plan="pro"
 data-trustlytics-event-property-billing="yearly">Pro (yearly)</a>

In the report you then look at two breakdowns under the event "Plan selected":

• plan: starter (40%), pro (50%), enterprise (10%)
• billing: monthly (70%), yearly (30%)

You can combine as many properties as you need. 20 per event at most.

The same approach works for anything that can be split into categories: whitepaper downloads by topic, the language choice in your menu, filter clicks in your shop, and star ratings. Always one event, many properties.

Example 5: sending a numeric value along

Properties store text. But sometimes you need a number you can do math with. An order value, for example. That is what data-trustlytics-event-value is for.

The value has to be a number, with a period as the decimal separator and no currency symbol:

<button data-trustlytics-event="Order completed"
  data-trustlytics-event-value="125.00">Buy now</button>

Usually your shop system sets this value automatically to the real cart amount before the button appears:

// Just before the buy button becomes clickable:
button.dataset.trustlyticsEventValue = String(cartTotal); // for example "89.50"

Leave the attribute out or let it stay empty, and the event still gets counted. Just without a value.

What else a value is worth using for: ratings (1 to 5 stars), the number of items in a cart, how many seconds of a video were played, the number of licenses selected. Any time it is not just about something happening but also about how much.

Example 6: controlling the trigger

Normally Trustlytics works out for itself when an event should fire. With a link that is the click, with a form the submit, with a dropdown the change. In the vast majority of cases you do not have to worry about it.

If you want to decide it yourself anyway, use data-trustlytics-event-on. There are three values to pick from:

An example where this pays off. You have a dropdown for the language and want to know which one gets picked. A click on it tells you nothing, because it always gets clicked. What matters is the change:

<select data-trustlytics-event="Language changed"
  data-trustlytics-event-on="change">
  <option value="en">English</option>
  <option value="es">Español</option>
  <option value="fr">Français</option>
</select>

Example 7: feedback on this article (how we do it ourselves)

Under every support article you find the question "Was this article helpful?" with two thumbs. We measure that with Trustlytics. What we recommend to you, we use ourselves. Here is what the code looks like:

<section class="helpful">
 <span>Was this article helpful?</span>
 <div class="helpful-btns">
 <button class="helpful-btn"
 title="Yes"
 data-trustlytics-event="Support article:Set up events"
 data-trustlytics-event-property-helpful="Yes">
 <!-- Thumbs up  -->
 </button>
 <button class="helpful-btn"
 title="No"
 data-trustlytics-event="Support article:Set up event"
 data-trustlytics-event-property-helpful="No">
 <!-- Thumbs down -->
 </button>
 </div>
</section>

Why we built it exactly this way:

1. The event name contains the article title. Instead of just "Feedback" we write "Support article:Set up events". That way we see later which article the feedback came from. With 50 articles, "Feedback" on its own would be worthless.
2. Both buttons fire the same event. The difference sits in the property, helpful="Yes" or helpful="No". In the report we see at a glance that 80% say yes and 20% say no. At 20% no, we know this article has to get better.

Which actions are detected automatically?

Trustlytics picks up these clicks automatically. There is nothing extra for you to set:

Rules and limits

How to check that it works

1. Place the marker in your HTML (like in the examples above).
2. Save the change on your website.
3. Open your website in a new browser window.
4. Click the marked element.
5. Switch to the "Events" area in Trustlytics. The entry appears live.

Tips for choosing names

• Use terms people understand. "Newsletter signup" is better than "form1".
• In the event name, spaces and accented characters are allowed. "Appointment booked" or "Plan selected" work without a problem.
• In property names, lowercase letters, numbers, and underscores only. So plan_type is fine. plan-type or Plan are not.
• Property values may contain anything. "pro tier", "39.90 USD", "US-CA". No problem.
• Stick to one spelling. "Newsletter signup" and "Newsletter sign up" are two different events to Trustlytics. You only notice that when the report splits your numbers across two rows.

Privacy

One request: do not write personal data into the values. No email addresses, no names, no phone numbers.

• Bad: data-trustlytics-event-property-email="john.doe@example.com"
• Good: data-trustlytics-event-property-segment="existing_customer"

Removing an event

Simply delete the data-trustlytics-event attribute from your HTML. From that moment on nothing gets counted anymore. Data already collected stays in your reports.

Common stumbling blocks

Five things that trip people up most often during setup:

• Capital letters in the property name. property-Plan does not work, property-plan does. In the event name, on the other hand, anything goes. Almost everybody misses that difference once.
• Two spellings for the same thing. "Demo booked" today, "Demo Booked" tomorrow. The report then holds two events, and neither one shows the full number.
• The attribute sits on the wrong element. On the form, the submit counts, on the button inside it, the click. Both are correct, but they measure different things.
• A currency symbol in the value. data-trustlytics-event-value="USD 125" is not a number. The correct form is 125.00, with nothing else.
• Twenty events marked at once. After that, the list is full and the overview is gone. Start with three to five, the most important ones.

Common questions

What if somebody clicks several times very quickly?
Every click counts separately. If somebody clicks the same button three times in a row, you see three events. That is intentional, because Trustlytics does not want to guess what you mean to count. The limit is 200 events per visit.

Are bots counted?
No. Search engine crawlers and bots get filtered out automatically.

How accurate is the counting?
Every event gets saved. The current day is evaluated live, the values from the previous day appear final the next morning.

Does this also work with React, Vue, or Next.js?
Yes. The data-trustlytics-event attribute works in every framework. Just set it in the JSX or the template, the same way as in plain HTML..

What happens if I change a property later?
If you write property-plan="starter" today and property-plan="basic" tomorrow, Trustlytics counts both separately. In the report, you see both values next to each other.

Can I change markers afterward?
Yes, at any time. Old events stay under the old name. New ones come in under the new name.

What is the difference between an event value and a property?
A property stores text and splits your event into categories, by plan or language, for example. The event value stores a number you can do math with, an amount, for example. Rule of thumb: if you want to group later, use a property. If you want to add things up, use the value

Can I use a value and properties at the same time?
Yes, and with orders, that is actually the normal case. The value carries the amount, a property the payment method or the country. The two do not get in each other's way.

Do I even need data-trustlytics-event-on?
In most cases, no. Trustlytics works out by itself whether something was clicked, submitted, or selected. You only need it when you want to override that default on purpose.

Do my own clicks get counted?
Yes. When you click the button yourself to test it, that is an event like any other. On smaller websites, it makes a difference, so count on the first entries coming from you.