eff_matomo 0.1.1

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 0919a5f8c95ff41737d832f9055262230a4d377ad1ed4ff4d4c1549e6cd49021
+  data.tar.gz: bd14a94d8484777a0081de23e7366513f17aab67cd5a7bccab4726ee6b405a32
+SHA512:
+  metadata.gz: 0adcbe9d7bf799fb9e11f0a7cb48d0d2ff7543a8b770dc96780082aebe76c8b3109518bfa9e5f1be382e87a0ad78b17715f527f8495b60cd070d881ad5ed2dbf
+  data.tar.gz: 6aa1698f1643997c1134933783fafa56faee12fedbeb0a7d2c0c0b09a18ce2f1757102f94801fbfd64706d7a5dc64b487ade41f13e51aa75d6711e393bcc75b2

data/.gitignore

@@ -0,0 +1,11 @@
+/.bundle/
+/.yardoc
+/_yardoc/
+/coverage/
+/doc/
+/pkg/
+/spec/reports/
+/tmp/
+
+# rspec failure tracking
+.rspec_status

data/.rspec

@@ -0,0 +1,3 @@
+--format documentation
+--color
+--require spec_helper

data/.travis.yml

@@ -0,0 +1,5 @@
+sudo: false
+language: ruby
+rvm:
+  - 2.3.1
+before_install: gem install bundler -v 1.16.2

data/Gemfile

@@ -0,0 +1,6 @@
+source "https://rubygems.org"
+
+git_source(:github) {|repo_name| "https://github.com/#{repo_name}" }
+
+# Specify your gem's dependencies in eff_matomo.gemspec
+gemspec

data/Gemfile.lock

@@ -0,0 +1,66 @@
+PATH
+  remote: .
+  specs:
+    eff_matomo (0.1.0)
+      activesupport
+      httparty
+
+GEM
+  remote: https://rubygems.org/
+  specs:
+    activesupport (5.2.1)
+      concurrent-ruby (~> 1.0, >= 1.0.2)
+      i18n (>= 0.7, < 2)
+      minitest (~> 5.1)
+      tzinfo (~> 1.1)
+    addressable (2.5.2)
+      public_suffix (>= 2.0.2, < 4.0)
+    concurrent-ruby (1.0.5)
+    crack (0.4.3)
+      safe_yaml (~> 1.0.0)
+    diff-lcs (1.3)
+    hashdiff (0.3.7)
+    httparty (0.16.2)
+      multi_xml (>= 0.5.2)
+    i18n (1.1.0)
+      concurrent-ruby (~> 1.0)
+    minitest (5.11.3)
+    multi_xml (0.6.0)
+    public_suffix (3.0.3)
+    rake (10.5.0)
+    rspec (3.8.0)
+      rspec-core (~> 3.8.0)
+      rspec-expectations (~> 3.8.0)
+      rspec-mocks (~> 3.8.0)
+    rspec-core (3.8.0)
+      rspec-support (~> 3.8.0)
+    rspec-expectations (3.8.1)
+      diff-lcs (>= 1.2.0, < 2.0)
+      rspec-support (~> 3.8.0)
+    rspec-mocks (3.8.0)
+      diff-lcs (>= 1.2.0, < 2.0)
+      rspec-support (~> 3.8.0)
+    rspec-support (3.8.0)
+    safe_yaml (1.0.4)
+    thread_safe (0.3.6)
+    tzinfo (1.2.5)
+      thread_safe (~> 0.1)
+    vcr (4.0.0)
+    webmock (3.4.2)
+      addressable (>= 2.3.6)
+      crack (>= 0.3.2)
+      hashdiff
+
+PLATFORMS
+  ruby
+
+DEPENDENCIES
+  bundler (~> 1.16)
+  eff_matomo!
+  rake (~> 10.0)
+  rspec (~> 3.0)
+  vcr
+  webmock
+
+BUNDLED WITH
+   1.16.2

data/LICENSE.txt

@@ -0,0 +1,21 @@
+The MIT License (MIT)
+
+Copyright (c) 2018 vivian
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in
+all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
+THE SOFTWARE.

data/README.md

@@ -0,0 +1,78 @@
+# 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'
+```
+
+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.
+
+### 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:
+```
+# 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 referrers
+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 occured 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:
+```
+# Get the top pages under a certain path, for example under "/articles"
+pages = Matomo::VisitedPage.where(base_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
+```
+
+## 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).

data/Rakefile

@@ -0,0 +1,6 @@
+require "bundler/gem_tasks"
+require "rspec/core/rake_task"
+
+RSpec::Core::RakeTask.new(:spec)
+
+task :default => :spec

data/bin/console

@@ -0,0 +1,14 @@
+#!/usr/bin/env ruby
+
+require "bundler/setup"
+require "matomo"
+
+# You can add fixtures and/or initialization code here to make experimenting
+# with your gem easier. You can also use a different console, if you like.
+
+# (If you use this, don't forget to add pry to your Gemfile!)
+# require "pry"
+# Pry.start
+
+require "irb"
+IRB.start(__FILE__)

data/bin/setup

@@ -0,0 +1,8 @@
+#!/usr/bin/env bash
+set -euo pipefail
+IFS=$'\n\t'
+set -vx
+
+bundle install
+
+# Do any other automated setup that you need to do here

data/eff_matomo.gemspec

@@ -0,0 +1,33 @@
+
+lib = File.expand_path("../lib", __FILE__)
+$LOAD_PATH.unshift(lib) unless $LOAD_PATH.include?(lib)
+require "matomo/version"
+
+Gem::Specification.new do |spec|
+  spec.name          = "eff_matomo"
+  spec.version       = Matomo::VERSION
+  spec.authors       = ["vivian"]
+  spec.email         = ["vivian@eff.org"]
+
+  spec.summary       = %q{Utilities for EFF applications accessing the Matomo API}
+  spec.homepage      = "https://github.com/efforg/eff-matomo"
+  spec.license       = "MIT"
+
+  # Specify which files should be added to the gem when it is released.
+  # The `git ls-files -z` loads the files in the RubyGem that have been added into git.
+  spec.files         = Dir.chdir(File.expand_path('..', __FILE__)) do
+    `git ls-files -z`.split("\x0").reject { |f| f.match(%r{^(test|spec|features)/}) }
+  end
+  spec.bindir        = "exe"
+  spec.executables   = spec.files.grep(%r{^exe/}) { |f| File.basename(f) }
+  spec.require_paths = ["lib"]
+
+  spec.add_dependency "activesupport"
+  spec.add_dependency "httparty"
+
+  spec.add_development_dependency "bundler", "~> 1.16"
+  spec.add_development_dependency "rake", "~> 10.0"
+  spec.add_development_dependency "rspec", "~> 3.0"
+  spec.add_development_dependency "webmock"
+  spec.add_development_dependency "vcr"
+end

data/lib/matomo.rb

@@ -0,0 +1,156 @@
+require "matomo/version"
+require 'matomo/railtie' if defined?(Rails)
+require "active_support/core_ext/hash"
+require "active_support/core_ext/string"
+require "httparty"
+
+module Matomo
+  class Referrer
+    attr_accessor :label, :visits
+
+    def initialize(params)
+      @label = params["label"]
+      @visits = params["nb_visits"]
+      @actions = params["nb_actions"]
+    end
+
+    def actions_per_visit
+      return 0 unless @actions and @visits
+      (@actions/@visits.to_f).round(1)
+    end
+
+    def self.top() where end
+
+    def self.where(**args)
+      params = { method: "Referrers.getAll" }.merge(
+        Matomo.date_range_params(args[:start_date], args[:end_date])
+      )
+      if args[:path]
+        params[:segment] = "pageUrl==#{Matomo.tracked_site_url}#{args[:path]}"
+      end
+      resp = Matomo.get(params)
+      return [] if resp.response.code != "200"
+      resp.map{ |x| new(x) }
+    end
+  end
+
+  class VisitedPage
+    attr_accessor :label, :hits, :visits
+
+    def initialize(base_path, params)
+      @base_path = base_path
+      @label = params["label"].sub!(/^\//, "") if params["label"]
+      @hits = params["nb_hits"]
+      @visits = params["nb_visits"]
+    end
+
+    def path
+      "/#{@base_path}/#{@label}"
+    end
+
+    def self.where(**args)
+      get_subtables unless @subtables
+      # Remove leading and trailing slashes to match Matomo label format.
+      base_path = args[:base_path].gsub(/^\/|\/$/, "")
+      return [] unless @subtables[base_path]
+
+      resp = Matomo.get({
+        method: "Actions.getPageUrls",
+        idSubtable: @subtables[base_path],
+      })
+      return [] if resp.response.code != "200"
+      resp.map{ |x| new(base_path, x) }
+    end
+
+    def self.get_subtables
+      # Get a mapping from resource paths to Matomo page view subtable ids
+      resp = Matomo.get({
+        method: "Actions.getPageUrls",
+        filter_limit: 50,
+      })
+      if resp.response.code == "200"
+        @subtables = resp.map{|x| [x["label"], x["idsubdatatable"]]}.to_h
+      else
+        @subtables = {}
+      end
+    end
+  end
+
+  def self.visits_graph_url
+    base_url + "?" + default_api_params.merge({
+      method: "ImageGraph.get",
+      apiModule: "VisitsSummary",
+      apiAction: "get",
+      token_auth: "anonymous",
+      width: 800,
+      height: 400,
+      period: "day",
+    }).to_query
+  end
+
+  def self.top_pages_url
+    base_portal_url+"&category=General_Actions&subcategory=General_Pages"
+  end
+
+  def self.top_referrers_url
+    base_portal_url+"&category=Referrers_Referrers&subcategory=Referrers_WidgetGetAll"
+  end
+
+  private
+
+  def self.get(params)
+    url = base_url + "?" + default_api_params.merge(params).to_query
+    HTTParty.get(url)
+  end
+
+  def self.base_url
+    ENV["MATOMO_BASE_URL"] || "https://anon-stats.eff.org"
+  end
+
+  def self.site_id
+    ENV["MATOMO_SITE_ID"]
+  end
+
+  # ##
+  # Gnarly base url for finding pages on the Matomo web portal
+  def self.base_portal_url
+    "#{base_url}/index.php?module=CoreHome&action=index&"\
+    "idSite=#{site_id}&period=#{default_api_params[:period]}&date=#{default_api_params[:date]}&updated=1#?"\
+    "idSite=#{site_id}&period=#{default_api_params[:period]}&date=#{default_api_params[:date]}"\
+  end
+
+  def self.default_api_params
+    {
+      module: "API",
+      idSite: site_id,
+      format: "JSON",
+      period: "range",
+      date: "last30",
+      filter_limit: 5
+    }
+  end
+
+  def self.date_range_params(start_date, end_date)
+    date_format = "%Y-%m-%d"
+    end_date = end_date || Date.today
+    start_date = start_date || end_date - 30.days
+    {
+      period: "range",
+      date: start_date.strftime(date_format) + "," + end_date.strftime(date_format)
+    }
+  end
+
+  ##
+  # The full url of a tracked page is sometimes required by the API, eg. when
+  # scoping by page.  We can load the base url from the environment or by
+  # making an API call.
+  def self.tracked_site_url
+    return ENV["MATOMO_TRACKED_SITE_URL"] if ENV["MATOMO_TRACKED_SITE_URL"]
+    return @tracked_site_url if @tracked_site_url
+    resp = get({
+      method: "SitesManager.getSiteUrlsFromId"
+    })
+    return nil if resp.response.code != "200" || resp.length == 0
+    @tracked_site_url = resp[0]
+  end
+end

data/lib/matomo/railtie.rb

@@ -0,0 +1,6 @@
+require 'matomo/view_helpers.rb'
+module Matomo
+  class Railtie < Rails::Railtie
+    ActionView::Base.send :include, Matomo::ViewHelpers
+  end
+end

data/lib/matomo/version.rb

@@ -0,0 +1,3 @@
+module Matomo
+  VERSION = "0.1.1"
+end

data/lib/matomo/view_helpers.rb

@@ -0,0 +1,23 @@
+module Matomo
+  module ViewHelpers
+    def matomo_tracking_url
+      "https://anon-stats.eff.org/js/?" + {
+        idsite: Matomo.site_id,
+        rec: 1,
+        action_name: page_title,
+        url: request.original_url
+      }.to_param
+    end
+
+    def matomo_tracking_embed
+      content_tag(:div, id: "anon-stats") do
+        content_tag(:noscript) do
+          content_tag(:img, src: matomo_tracking_url, style: "border:0", alt: "")
+        end
+        javascript_tag do
+          "document.getElementById('anon-stats').innerHTML = '<img src=\"#{matomo_tracking_url}\"?urlref=' + encodeURIComponent(document.referrer) + 'style=\"border:0\" alt=\"\" />';".html_safe
+        end
+      end
+    end
+  end
+end

metadata

@@ -0,0 +1,157 @@
+--- !ruby/object:Gem::Specification
+name: eff_matomo
+version: !ruby/object:Gem::Version
+  version: 0.1.1
+platform: ruby
+authors:
+- vivian
+autorequire: 
+bindir: exe
+cert_chain: []
+date: 2018-10-22 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: activesupport
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+- !ruby/object:Gem::Dependency
+  name: httparty
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+- !ruby/object:Gem::Dependency
+  name: bundler
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.16'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.16'
+- !ruby/object:Gem::Dependency
+  name: rake
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '10.0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '10.0'
+- !ruby/object:Gem::Dependency
+  name: rspec
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '3.0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '3.0'
+- !ruby/object:Gem::Dependency
+  name: webmock
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+- !ruby/object:Gem::Dependency
+  name: vcr
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+description: 
+email:
+- vivian@eff.org
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- ".gitignore"
+- ".rspec"
+- ".travis.yml"
+- Gemfile
+- Gemfile.lock
+- LICENSE.txt
+- README.md
+- Rakefile
+- bin/console
+- bin/setup
+- eff_matomo.gemspec
+- lib/matomo.rb
+- lib/matomo/railtie.rb
+- lib/matomo/version.rb
+- lib/matomo/view_helpers.rb
+homepage: https://github.com/efforg/eff-matomo
+licenses:
+- MIT
+metadata: {}
+post_install_message: 
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubyforge_project: 
+rubygems_version: 2.7.7
+signing_key: 
+specification_version: 4
+summary: Utilities for EFF applications accessing the Matomo API
+test_files: []