iiab/roles/matomo

= Matomo README

https://matomo.org/[Matomo] is a web analytics alternative to Google Analytics, emphasizing privacy and data ownership, that you can use with https://internet-in-a-box.org[Internet-in-a-Box] (IIAB).

== Install it

Prior to installing Matomo with IIAB, the default URL (http://box.lan/matomo) can be customized in https://wiki.iiab.io/go/FAQ#What_is_local_vars.yml_and_how_do_I_customize_it%3F[/etc/iiab/local_vars.yml]

One way to do that is by changing these 2 lines:

----
iiab_hostname: box
iiab_domain: lan
----

Or, you can change the Matomo URL by putting your IIAB IP Address in a line like:

----
matomo_host_url: http://192.168.0.199
----

Either way, consider setting a Matomo username and password using lines like:

----
matomo_db_user: Admin
matomo_db_pass: changeme
----

Also ensure that your `/etc/iiab/local_vars.yml` contains these lines:

----
matomo_install: True
matomo_enabled: True
----

_Finally, continue to https://download.iiab.io[install IIAB], e.g. by running `sudo iiab`, until software installation is complete._

== Use it

Log in to your IIAB's full Matomo URL, e.g. http://box.lan/matomo, as arranged above.

Take a look at Matomo's official guides to further set this up: https://matomo.org/guides/


WARNING: Matomo won't show any traffic statistics until after 1 day or reboot (which are the events that trigger the log scraper!)

=== Getting Started

Matomo is developed with commercial websites in mind. After navigating to http://box.lan/matomo and logging in with the username and password you set above, you will see a variety of references to revenue, marketplaces, and other terms focused on commercialization and advertising. Don't worry about that.

The heart of Matomo's value for you is in the navigation bar on the left side of the page. Click on *Visitors* and then below *Visitors*, *Overview*, to see how many different users are visiting your site. The top of the page will show a graph of how many visits occur on each day (although your device may not keep track of time when it is off and has no connection to the Internet, so this graph might not be perfectly accurate). Below the graph, you'll see some overall statistics, like how many unique visitors you've had. Matomo thinks of visitors in terms of devices, so it won't know if two people are connecting to your Internet-in-a-Box using the same phone. There are several other interesting statistics here, like the average visit duration, or average time your visitors are spending using Internet-in-a-Box.

Below the *Visitors* button is a second button, *Behavior*. Click on the *Pages* button after clicking *Behavior* and you can see the various pages that have been visited by your users. You may not see activity from the most recent day, since Matomo only updates its records once per day.

=== IIAB Tips, Tricks, and Gotchas

1. If your Internet-in-a-Box setup is without power and Internet access, it may not be able to keep time correctly. This is okay! But it means that the time-of-visit information in Matomo will not be correct.

2. One thing Matomo can't track correctly is navigation within KA Lite (Khan Academy) pages. If your users are spending a lot of time here, it won't be visible in the Matomo statistics.

3. Time Zones: The Matomo installer's default behavior in "Configure Matomo to track IIAB" is to pick up the system time zone when none is supplied. If this doesn't work, you can set the time zone to whatever you prefer from the Matomo home page. In testing, Matomo picked up the system time zone on a regular Multipass Ubuntu instance. However, it was unable to do so on a VirtualBox Ubuntu instance. Thus, we provide a fallback behavior "Fallback Configure Matomo to track IIAB" that picks an arbitrary time zone. The fallback fires only when the form with an empty time zone is submitted and returns a 200 status code instead of 302, indicating that form submission failed.


== Credits

Carl Wivagg