matomo-reporting-js

---

This module lets you use the reporting API. If you wish to set up visit tracking, please see https://developer.matomo.org/guides/tracking-javascript-guide

Features:

• Automatic query batching
• Full async/await support
• Full and easy access to the reporting API

Getting started

Install from NPM by running npm i -S matomo-reporting-js, or yarn add matomo-reporting-js Afterwards, you can pull the module in with import MatomoApi from 'matomo-reporting-js'

Options

Two types of options exist:
Options to pass when creating the instance with new:
Show code (click to expand)
```js new MatomoApi({

// Mandatory
// If you're using isomorphic-fetch, it's window.fetch in the browser 
// and global.fetch in Node. Otherwise, please consult your implementation's
// manual if any. Most browsers have window.fetch available by default.
'fetch': global.fetch,

// Optional, default: undefined
// Defines the agent to be used for the fetch call.
// Useful if you want to ignore SSL errors in server side applications.
'agent': new https.Agent(),

// Optional, default: undefined
// If you specify a handler, network and API errors will not cause the promise
// to reject and the Error instance will be passed to the function.
// If the handler returns anything, it will be used for the promise response.
// Otherwise, the promise will reject for any error.
'handler': (error) => sendToLoggingService(error),

}, {

// Mandatory
// Set your Matomo instance's URL here
// Depending on your server configuration, index.php may be required at the end.
'endpoint': 'https://demo.matomo.org/index.php',

// Mandatory
// Your site ID you wish to track with this instance of the client
'idSite':   3,

// Optional, default: 100
// This number (in miliseconds) dictates how much to wait for queries before
// sending the bulk request to the API.
'patience': 100,

// Optional, default: undefined
// This string defines your authentication token if your site is not set
// to public.
'token_auth': 'asdfghjkl1234567',

// Optional, default: {}
// Additional network headers to send in a key-value format
'headers': {},

// Optional, default: false
// If true, the module will log its requests to the console before sending
'debug': false,

}) ```

---

Options to pass when running a query:
Show code (click to expand)
```js const api = new MatomoApi(options)
api.query({

// Mandatory
// The reporting API method you wish to use
'method': 'ExampleAPI.getMatomoVersion',

// Optional, default: 'month'
// The timeframe you'd like to request data for
'period': 'month',

// Optional, default: 'today'
// The start date the API should use to start from
'date': 'today',

// You must also put API specific options here as well, see the
// examples below.

}), ```

Examples:

There are two main ways you can use this package. First, the standard Promise.all, which will net you an array of results that includes all responses.
Show code (click to expand)
```js import MatomoApi from 'matomo-reporting-js' import fetch from 'node-fetch'
// Create and configure the interface const api = new MatomoApi(options)
// Example implementation const run = async () => {

// Matomo provides some example APIs that return pre-defined strings.
// Here, we run queries we want to receive.
//
// For a full list of what you can run, see https://developer.matomo.org/api-reference/reporting-api

const results = await Promise.all([
  // Gets the running Matomo version
  api.query({
    'method': 'ExampleAPI.getMatomoVersion',
  }),
  // Adds two number arguments together
  // You can specify any argument that the reporting API accepts.
  api.query({
    'method': 'ExampleAPI.getSum',
    'a':      6,
    'b':      3,
  }),
  // Returns an object that has no data, but is otherwise successful
  api.query({
    'method': 'ExampleAPI.getNull',
  }),
  // Returns a string-key dictionary that consists of arrays with mixes types
  api.query({
    'method': 'ExampleAPI.getMultiArray',
  }),
])

return JSON.stringify(results, null, 2)

}
run() .then(console.log) .catch(console.error)
```

---

More conveniently, you can also use it for singular requests and as traditional promises. Query batching will work automatically this way as well, even across functions and files.
Show code (click to expand)
```js const run = () => {

api.query({
  'method': 'ExampleAPI.getMatomoVersion',
})
.then(console.log)
.catch(console.error)

api.query({
  'method': 'ExampleAPI.getSum',
  'a':      6,
  'b':      3,
})
.then(console.log)
.catch(console.error)

api.query({
  'method': 'ExampleAPI.getNull',
})
.then(console.log)
.catch(console.error)

api.query({
  'method': 'ExampleAPI.getMultiArray',
})
.then(console.log)
.catch(console.error)

}
run()
```