matomo-reporting-js v1.2.0

Easily access your Matomo's reporting API from within Node or a browser

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:

// 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,

})

</details>

----

Options to pass when running a query:

<details>
<summary><strong>Show code</strong> (click to expand)</summary>

```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.

// 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)

</details>

----

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.

<details>
<summary><strong>Show code</strong> (click to expand)</summary>

```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()