Getting Started

Installation

To install flask-matomo2:

pip install flask-matomo2

Simple integration

from flask import Flask, jsonify
from flask_matomo2 import Matomo

app = Flask(__name__)
matomo = Matomo(
  app,
  matomo_url="https://matomo.mydomain.com",
  id_site=5,
  token_auth="XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX", # Optional
  ignore_routes=["/ignore/this/path"], # Optional, can be set with the ignore decorator
  routes_details={"/foo": {"action_name": "FOO"}}, # Optional, can be set with the details decorator
  ignored_patterns=[".*/html.*"], # Optional
  ignored_ua_patterns=[".*bot.*"], # Optional, ignores requests made where the User-Agent matches any of these patterns
)

@app.route("/")
def index():
  return jsonify(route="/")

@app.route("/ignore/this/path")
def ignore_this_path():
  return jsonify(route="/ignore/this/path")

@app.route("/ignore/this/path/also")
@matomo.ignore()
def ignore_this_path():
  return jsonify(route="/ignore/this/path/also")

@app.route("/foo")
def foo():
  return jsonify(route="/foo")

@app.route("/foo2")
@matomo.details(route="/foo2", action_name="FOO/2")
def _foo2():
  return jsonify(route="/foo2")

@app.route("/html/path")
@app.route("/some/html/path")
@app.route("/some/path.html")
def html_content():
  return "<html>Prefer tracking html with Matomo JS tracking</html>"

if __name__ == "__main__":
  app.run()

In the code above:

  1. The Matomo object is created by passing in the Flask application and arguments to configure Matomo.

  2. The matomo_url parameter is the url to your Matomo installation.

  3. The id_site parameter is the id of your site. This is used if you track several websites with on Matomo installation. It can be found if you open your Matomo dashboard, change to site you want to track and look for &idSite= in the url.

  4. The token_auth parameter can be found in the area API in the settings of Matomo. It is required for tracking the ip address, so if skipping this will skip tracking ip-addresses.

  5. The route /ignore/this/path is ignored by the call to the Matomo constructor.

  6. The route /ignore/this/path/also is ignored by using the ignore decorator.

  7. The route /foo will be tracked with action_name=FOO by the call to the Matomo constructor.

  8. The route /foo2 will be tracked with action_name=FOO/2 by using the details, note the needed explicit naming of the route name if the function name doesn’t match the route name.

  9. The routes /html/path, /some/html/path and /some/path.html will be ignored because they match a ignored_pattern.

  10. All requests made where the User-Agent matches any of the patterns in ignored_ua_patterns, will be ignored.

The code can also be written as:

Late activation

Sometimes you can’t create the Matomo object directly, then you can mark as to be activated later:

In this example the matomo object is defined in the file plugins.py and can be used by routes defined in other files. But the matomo_url and id_site is only available when the app is created by the factory function create_app.

In this example we assume that our app is hosted at https://example.com/dir by Apache or nginx and our app is run locally. To allow Matomo to track the correct urls, we can set base_url=”https://example.com/dir”. (The same can also be solved by setting base_url in gunicorn).

Time custom parts of a request

Sometimes you want to track the time of a call to some other api call.

You can then use PerfMsTracker to track that call.

In this example, the call to the other api is tracked with the key pf_srv.