matomo-org / matomo-org/developer-documentation

Clarify behaviour of using both matomoAsyncInit and _paq.push()

Open
#779 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

I have not found any clear documentation what happens if you use `_paq` push in combination with `matomoAsyncInit`. This could lead to some unexpected behaviour that could not be explained with a simple documentation link.

Given the following tracker integration:

```
var _paq = window._paq = window._paq || [];

(function() {
var siteIdFirst = 1;
var siteIdSecond = 2;
var urlFirst = 'https://first.matomo.instance/matomo.php';
var urlSecond = 'https://second.matomo.instance/matomo.php';

window.matomoAsyncInit = function() {
var tracker = Matomo.getAsyncTracker(urlSecond, siteIdSecond);

tracker.MyPlugin.disable();
};

_paq.push(['setTrackerUrl', urlFirst]);
_paq.push(['setSiteId', siteIdFirst]);
_paq.push(['trackPageView']);

// regular script tag integration
})();
```

From the code one could expect that `MyPlugin.disable()` would be called on the tracker for the second url/site. But, this is not the case.

The call to `getAsyncTracker()` in `matomoAsyncInit` will create the first tracker. All queued `_paq` commands are executed for this instance, overwriting the parameters given to the `getAsyncTracker()` call and resulting in only a single tracker instance being set up.

Adding `_paq.push(['addTracker', urlSecond, siteIdSecond])` before the script tag creation will create that second tracker, but it will not be used inside `matomoAsyncInit`. The first tracker is being returned there.

It should be clearer that `matomoAsyncInit` is getting executed before the first tracker instance is created. And the first call to `getAsyncTracker()` (and the other methods affected) is running all queued `_paq` commands, requiring to call `getAsyncTracker` twice if you want to e.g. deactivate a plugin only on the second tracker.

Refs matomo-org/matomo#21976.

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 by tracing the documented interaction between matomoAsyncInit, Matomo.getAsyncTracker(), _paq.push(), and addTracker(). Confirm the order in which the first tracker and queued commands are processed, then update the relevant developer documentation to explain the observed tracker behavior and when repeated getAsyncTracker() calls are needed.

Written by the indexing model from the issue text.

Assessment

Tech stack
javascript
Domain
documentation
Issue type
Documentation
Difficulty
3/5
Estimated time
1-2 days
Activity status
Stale
Clarity
Mostly clear
Newbie friendliness
45/100

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.