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

[mneudert]

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.