https://github.com/efforg/eff_matomo
Matomo API in Ruby
https://github.com/efforg/eff_matomo
Last synced: about 7 hours ago
JSON representation
Matomo API in Ruby
- Host: GitHub
- URL: https://github.com/efforg/eff_matomo
- Owner: EFForg
- License: mit
- Created: 2018-10-22T23:14:20.000Z (over 7 years ago)
- Default Branch: master
- Last Pushed: 2019-06-04T22:42:26.000Z (about 7 years ago)
- Last Synced: 2025-01-03T09:17:57.518Z (over 1 year ago)
- Language: Ruby
- Size: 35.2 KB
- Stars: 1
- Watchers: 12
- Forks: 0
- Open Issues: 6
-
Metadata Files:
- Readme: README.md
- License: LICENSE.txt
Awesome Lists containing this project
README
# EFF Matomo
The EFF Matomo gem provides utilities for integrating our Ruby applications with our analytics tool, Matomo.
## Installation
Add this line to your application's Gemfile:
```ruby
gem 'eff_matomo', require 'matomo'
```
And then execute:
$ bundle
Or install it yourself as:
$ gem install eff_matomo
## Usage
### Configuration
This gem reads two environment variables:
* `MATOMO_SITE_ID`: The ID in Matomo of the app being tracked. **Required**.
* `MATOMO_BASE_URL`: The URL where Matomo is being hosted. Defaults to "https://anon-stats.eff.org".
### Adding the Matomo tracking embed to a Rails app
Add `<%= matomo_tracking_embed %>` to the footer of your application layout template.
`{action_name = [NAME]}` can be passed to set the action name manually. Otherwise, eff_matomo will attempt to use a `page_title` helper or else omit the action name.
### Displaying Matomo data
This gem provides allows users to import site usage data from Matomo to display in their application. It currently supports two types of data:
**Referrers** show how users are reaching the application. Usage example:
```ruby
# Get the top five referrers for the site
referrers = Matomo::Referrer.top
# Scope referrers by date range
referrers = Matomo::Referrer.where(start_date: Time.now - 1.month, end_date: Time.now)
# Only show referrers for a certain page within the app
referrers = Matomo::Referrer.where(path: "/action/my-important-action")
# Access information about each referrer
referrers.each() do |referrer|
puts referrer.label # eg. "facebook.com"
puts referrer.visits # Number of times a visit came from this referrer
puts referrer.actions_per_visit # Average number of actions that occurred during a visit
end
```
**Visited Pages** show the top pages within the application, both in terms of unique page views and overall number of hits. Usage example:
```ruby
# Get the top pages under a certain path, for example under "/articles"
pages = Matomo::Page.under_path("/articles")
# Access information about each page
pages.each() do |page|
puts page.label # eg. "/harm-reduction"
puts page.path # eg. "/acticles/harm-reduction"
puts page.hits # Overall number of hits on the page
puts page.visits # The number of distinct visits to the page
end
# Get views for a certain page, grouped by day
# Return format eg. { "2018-10-03": , "2018-10-04": , etc. }
pages = Matomo::Page.group_by_day("/articles/harm-reduction",
start_date: Time.now - 1.month, end_date: Time.now)
```
## Development
After checking out the repo, run `bin/setup` to install dependencies. Then, run `rake spec` to run the tests. You can also run `bin/console` for an interactive prompt that will allow you to experiment.
To install this gem onto your local machine, run `bundle exec rake install`. To release a new version, update the version number in `version.rb`, and then run `bundle exec rake release`, which will create a git tag for the version, push git commits and tags, and push the `.gem` file to [rubygems.org](https://rubygems.org).
## License
The gem is available as open source under the terms of the [MIT License](https://opensource.org/licenses/MIT).