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: If your IIAB URL is *not* http://box.lan, you may run into a big orange warning from Matomo that it has been configured to run from a different address. Here are the steps to fix this problem.

1. Copy the IP address listed in the box below "How do I fix this problem and how do I log in again?" For example, I see `trusted_hosts[] = "192.168.64.10"`, so I copy `"192.168.64.10"`.
2. Run `sudo nano /library/www/matomo/config/config.ini.php` to edit Matomo's config file.
3. Paste or type the IP address from Step 1 to replace `"box.lan"` in the `trusted_hosts` line, which should be about line 13. When I'm done, my line 13 says `trusted_hosts[] = "192.168.64.10"` instead of `trusted_hosts[] = "box.lan"`.
4. Refresh the Matomo homepage and the warning should be gone.
5. Optionally, see the https://forum.matomo.org/t/trusted-hostname/11963[advanced tips] in https://forum.matomo.org/[Matomo's Forum].

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 user name 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 can't 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 will 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 Khan Academy pages. If your users are spending a lot of time here, it won't be visible in the Matomo statistics.

== Credits

Carl Wivagg