matomo-org / matomo-org/developer-documentation

What exactly is action_name? (Maybe) Change its documentation.

Open
#735 0 comments 1 reaction 0 assignees View on GitHub

Nobody has claimed this yet.

Dominant language
PHP
Stars
58
Forks
88
Avg merge
6d 3h
Merged PRs (30d)
13

Description

For context: We are currently discussing implementing a tracker solution based on the [Tracking HTTP API](https://developer.matomo.org/api-reference/tracking-api).

The documentation lists `action_name` as one of the `Recommended parameter`s. It also states that "you should provide as much information as you can" with regard to the parameters. We understand this as setting the recommended parameters as frequent as possible.

Here is the [quoted](https://developer.matomo.org/api-reference/tracking-api) description of `action_name` from the documentation:
> action_name (recommended) — The title of the action being tracked. For page tracks this is used as page title. If enabled in your installation you may use the category tree structure in this field. For example, “game / register new user” would then create a group “game” and add the item “register new user” in it.

The second sentence of the quote makes it clear to me how to use `action_name` when tracking page views.

Now, I had a rather long discussion with one of my collegs on how to use `action_name` when not tracking a page view.
As a `Recommended parameter`, the documentation kind of suggests to set it in every tracking call if possible, but only gives advice on what to set it to when tracking page views.

Now, I view `action_name` more like a `page_name` and I only want to set it when tracking page views, while he wants to set it for every tracking call (to the name of the page the action happens on).

To prove my point, I did two things:
* I reffered to the JavaScript tracking API, which only uses `action_name` in [`logPageView`](https://github.com/matomo-org/matomo/blob/24e2ac94918659cc84fb6312af5b9bc559c009a4/js/piwik.js#LL4170C24-L4170C24). (Side question: Am I correct to treat the JavaScript implementation as a "Tracker Refference Implementation"?)
* I tracked an event using the event paramters `e_c` and `e_a`, and also set an `action_name`; The event was logged and I inspected the Matomo database directly, but found out that `action_name` for the event was recorded nowhere.

He on the other hand argued that:
* The documentation recommends it, so we should set it.
* Setting a parameter that *might* not be used doesn't hurt.

Since we could not come to an agreement on this matter, we are now asking what exactly `action_name` is and how/when we should use it?

Contributor guide

No contributing guide indexed for this repository

First steps

  1. Read the whole issue, then the project's contributing guide.
  2. Comment on the issue to say you are picking it up — it saves two people doing the same work.
  3. Fork the repository and make your change on a branch.
  4. Open a pull request that references the issue number.

Research direction

Start with the quoted Tracking HTTP API documentation and the referenced JavaScript implementation in js/piwik.js, especially logPageView. Compare how action_name is described and recorded for page views and events, then clarify its intended use in the API documentation with an unambiguous recommendation and examples.

Written by the indexing model from the issue text.

Assessment

Tech stack
javascript
Domain
api, documentation
Issue type
Documentation
Difficulty
3/5
Estimated time
1-2 days
Activity status
Stale
Clarity
Needs clarification
Newbie friendliness
35/100

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.