Skip to content

Add some segment documentation #416

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
merged 3 commits into from
Mar 16, 2021
Merged

Add some segment documentation #416

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
3 commits
Select commit Hold shift + click to select a range
f7393c5
Add some segment documentation
tsteur Jan 21, 2021
9271915
Update segments.md
tsteur Jan 21, 2021
fff52a2
Merge branch 'live' into segmentsdocs
tsteur Mar 16, 2021
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
1 change: 1 addition & 0 deletions app/helpers/Content/Category/DevelopInDepthCategory.php
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -34,6 +34,7 @@ public function getItems()
new Guide('reproducing-issues'),
new Guide('jstracker-core'),
new Guide('tracking-requests'),
new Guide('segments'),
new Guide('core-faqs'),
new RemoteLink('Matomo\'s Roadmap', 'https://matomo.org/roadmap/'),
]),
Expand Down
27 changes: 27 additions & 0 deletions docs/segments.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,27 @@
---
category: DevelopInDepth
title: Segments
---
# Matomo core - Segments

## How are segments encoded?

Segments are typically encoded three times:

* The first decode is on the whole segment: https://github.com/matomo-org/matomo/blob/3.x-dev/core/Segment.php#L104 . The corresponding encode was added in 3.6.0 here: https://github.com/matomo-org/matomo/blob/3.x-dev/plugins/Live/javascripts/SegmentedVisitorLog.js#L123
* the second decode is on individual conditions (ie, pageUrl==...): https://github.com/matomo-org/matomo/blob/3.x-dev/core/Segment/SegmentExpression.php#L91
* the third decode is on individual values: https://github.com/matomo-org/matomo/blob/3.x-dev/core/Segment/SegmentExpression.php#L112
Comment on lines +11 to +13
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Are the links on 3.x-dev branch on purpose?

Copy link
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

@sgiehl it was copied from a PR description. I guess it's fine to use 3.x because the code basically doesn't change anymore there. Could otherwise reference a 4.X version but in the end there's no difference


This means the value needs to be triple encoded for values like plus signs to be used properly in the segment. For more details see [#13481](https://github.com/matomo-org/matomo/pull/13481).

## Creating a segment instance

```php
$segment = new Piwik\Segment($definition, $idSites);
```

You need to use `urlencode($definition)` if the segment is sourced from the `segment` table or from `SegmentEditor.getAll`. Then it should be encoded before being used in the `Segment` class. If there is a lot of passing the string around before creating a `Segment`, then it would be hard to figure out what to use. For reference see [#17029](https://github.com/matomo-org/matomo/pull/17029).

## How do I get the correct expected segment hash for a segment?

Execute the `SegmentEditor.getAll` API method as this should include the expected segment hash.