Skip to content

Commit fd2e3bd

Browse files
metmarkosaricmetmarkosaric
committed
custom props fixes
1 parent c70a8a2 commit fd2e3bd

3 files changed

Lines changed: 39 additions & 43 deletions

File tree

‎docs/custom-props/for-custom-events.md‎

Lines changed: 35 additions & 35 deletions
Original file line numberDiff line numberDiff line change
@@ -2,62 +2,62 @@
22
title: Attach custom properties to custom events
33
---
44

5-
import useBaseUrl from '@docusaurus/useBaseUrl';
5+
## Send custom properties with custom events
66

7-
## Tag properties to custom events you want to track
7+
When you track a custom event, you can include property key-value pairs alongside it. This lets you capture additional context about the event, for example which pricing plan a visitor selected when clicking a sign-up button, or which content variation they were shown.
88

9-
Let's say you have a contact form both in the header and footer of your site. In addition to tracking submissions, you might want to know which section of your site the form was submitted on. Instead of creating separate goals for each form, you can send a custom property instead.
9+
### Using HTML class attributes
1010

11-
Similarly to how you define an event name inside the `class` attribute, you can use the format `plausible-event-<property>=<value>` to define custom properties. Following the same example, your code might look something like this:
11+
If you're using Plausible's class-based event tracking, add properties using the format `plausible-event-<property>=<value>` on the same element:
1212

1313
```html
14-
<body>
15-
<!-- header -->
16-
<form class="plausible-event-name=Form+Submit plausible-event-position=header">...</form>
17-
18-
<!-- footer -->
19-
<form class="plausible-event-name=Form+Submit plausible-event-position=footer">...</form>
20-
</body>
14+
<button class="plausible-event-name=Sign+Up plausible-event-plan=starter">...</button>
15+
<button class="plausible-event-name=Sign+Up plausible-event-plan=pro">...</button>
2116
```
2217

23-
Now, both form submissions would trigger the same `Form Submit` event, but the `position` property will be different.
18+
Both buttons trigger the same `Sign Up` event, but the `plan` property will differ between them.
2419

25-
:::tip To represent a space character in property values, you can use a `+` sign
26-
This is because you can't include the space character in the `class` attribute
20+
:::tip
21+
To represent a space in a property value, use a `+` sign. Space characters are not valid in class attributes.
2722
:::
2823

29-
You can add up to 30 classes for custom properties. Simply separate them with a space character like in the above example.
24+
You can add up to 30 properties per event by separating each class with a space.
3025

31-
:::note
32-
If you don't see a `plausible.init` call in your snippet, [upgrade your script](/script-update-guide)
33-
:::
26+
## Using the JavaScript method
3427

35-
## Using custom properties in goals and funnels
28+
If you're triggering events manually with JavaScript, pass properties as a second argument:
3629

37-
When [creating a goal from a custom event](goal-conversions.md), you can attach up to three custom properties to that goal.
30+
```js
31+
plausible('Sign Up', {props: {plan: 'pro', variation: 'homepage-cta'}})
32+
```
3833

39-
This allows you to define more precise goals. For example, you can create a single goal for `Form Submit` and limit it to specific property values such as `position=header` or `method=HTTP`.
34+
---
4035

41-
Goals with custom properties can also be [used inside funnels](funnel-analysis.md). This makes it possible to build funnels that track specific variations of the same event, such as different form locations, buttons or interaction types.
36+
## Create property-filtered goals
4237

43-
<details>
38+
When you [create a goal from a custom event](goal-conversions.md) in your site settings, you can optionally attach up to three property constraints to that goal definition.
4439

45-
<summary>
40+
A property-filtered goal only counts an event when both the event name and the property values match. For example, you can create a `Pro Sign Up` goal that only fires when a `Sign Up` event includes `plan=pro`. A separate `Starter Sign Up` goal would match `plan=starter`.
4641

47-
## Tag custom properties using the manual method
42+
This is distinct from simply sending properties with your events:
4843

49-
</summary>
44+
- **Sending a property with an event** records raw data. You can filter and analyze it in the dashboard after the fact.
45+
- **Attaching a property to a goal** makes the property part of the goal's definition. The goal only counts when that specific property value is present. It becomes a discrete conversion metric, not a filtered view of existing data.
5046

51-
This is an alternative option for those who are sending custom events manually with JavaScript, for example:
47+
---
5248

53-
```js
54-
plausible('Download')
55-
```
49+
## Use property-filtered goals in funnels
5650

57-
All you have to do is add the second argument to this function call with the custom properties as follows:
51+
Funnels in Plausible are built from goals, not raw events. Each funnel step must map to a defined goal.
5852

59-
```js
60-
plausible('Download', {props: {method: 'HTTP', position: 'footer'}})
61-
```
53+
If you want a funnel step to represent a specific variation of an event rather than all instances of it, you need a goal with the property constraint built in.
54+
55+
For example, a funnel that tracks:
56+
57+
1. Visitor views the pricing page
58+
2. Visitor clicks the Pro plan sign-up button
59+
3. Visitor completes registration
60+
61+
Step 2 requires a goal that matches only `Sign Up` events where `plan=pro`. Without the property constraint on the goal, that step would count any sign-up button click on the site regardless of which plan was selected.
6262

63-
</details>
63+
Once you've created property-filtered goals, you can [add them as funnel steps](funnel-analysis.md) the same way as any other goal.

‎docs/custom-props/for-pageviews.md‎

Lines changed: 1 addition & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -24,11 +24,7 @@ plausible.init({
2424
})
2525
```
2626

27-
That's it! You're now tracking custom properties alongside pageviews.
28-
29-
:::note
30-
If you don't see a `plausible.init` call in your snippet, [upgrade your script](/script-update-guide)
31-
:::
27+
You're now tracking custom properties alongside pageviews.
3228

3329
<details>
3430

‎docs/custom-props/introduction.md‎

Lines changed: 3 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -4,11 +4,11 @@ title: Introduction to custom properties
44

55
import useBaseUrl from '@docusaurus/useBaseUrl';
66

7-
You can attach custom properties (also known as [custom dimensions](https://plausible.io/blog/custom-dimensions-analytics) in Google Analytics) when sending pageviews or custom events to Plausible in order to create custom metrics. Custom properties allow you to collect and analyze metrics that we don't track automatically.
7+
Custom properties let you collect and analyze metrics that Plausible doesn't track automatically. You can attach them to pageviews or custom events to create your own segments and filters. If you're coming from Google Analytics, custom properties are equivalent to [custom dimensions](https://plausible.io/blog/custom-dimensions-analytics).
88

99
For example, say you want to track your blog posts by `author`. Every time a visitor lands on one of the posts, you can send a pageview with the property `author=...`. You can then filter your Plausible dashboard by a specific author to see all the relevant stats for the posts published by that particular writer.
1010

11-
Some other examples of stats you can get by sending custom properties:
11+
Other examples:
1212

1313
* Filter content by the publication date, page type, ID, tag or category
1414
* Filter visitors by login status or user role
@@ -35,7 +35,7 @@ Note that you must ensure that no personally identifiable information (PII) is s
3535

3636
Plausible will display `(none)` in your dashboard when you send a custom property key with no value, or `null`/`undefined` as a value. Also, when you send one event with a property (e.g. `author`) and another event with the same name, but without the `author` property, then you will also see the `(none)` value because the property has not been sent with every event.
3737

38-
When you filter your dashboard by a particular custom event and look at the "**Properties**" tab, you shouldn't see the `(none)` value there if all the relevant events have been sent with the property included. However, if you're viewing the "**Properties**" tab without any custom event filter, it returns all the events in your dashboard (including all regular pageviews) and many of these events may not have a property attached. Hence you see the `(none)` value.
38+
When you filter your dashboard by a particular custom event and look at the "**Properties**" tab, you should only see `(none)` if some of those events were sent without the property. However, if you're viewing the "**Properties**" tab without any custom event filter, it returns all the events in your dashboard (including all regular pageviews) and many of these events may not have a property attached. This is why you see the `(none)` value.
3939

4040
## Accepted values
4141

0 commit comments

Comments
 (0)