jekyll-ga-v2 1.0.0

data/jekyll-ga-v2.gemspec

@@ -0,0 +1,27 @@
+# coding: utf-8
+lib = File.expand_path("../lib", __FILE__)
+$LOAD_PATH.unshift(lib) unless $LOAD_PATH.include?(lib)
+
+require "jekyll-ga-v2/version"
+
+Gem::Specification.new do |spec|
+  spec.name          = "jekyll-ga-v2"
+  spec.summary       = "Jekyll Google Analytics integration"
+  spec.description   = "Google Analytics support in Jekyll blog to easily show the statistics on your website"
+  spec.version       = Jekyll::GoogleAnalyticsV2::VERSION
+  spec.authors       = ["z3nth10n"]
+  spec.email         = ["z3nth10n@gmail.com"]
+  spec.homepage      = "https://github.com/uta-org/jekyll-ga-v2"
+  spec.licenses      = ["MIT"]
+    
+  spec.files         = `git ls-files -z`.split("\x0").reject { |f| f.match(%r!^(test|spec|features|assets|versions)/!) }
+  spec.require_paths = ["lib"]
+    
+  spec.add_dependency "jekyll", "~> 3.0"
+  spec.add_dependency 'googleauth', '~> 0.8.0'
+  spec.add_dependency 'google-api-client', '~> 0.28.4'
+  spec.add_dependency 'chronic', '~> 0.10.2'
+ 
+  spec.add_development_dependency "rake", "~> 11.0"
+  spec.add_development_dependency "rspec", "~> 3.5"
+end

data/lib/jekyll-ga-v2.rb

@@ -0,0 +1,15 @@
+# Jekyll::GoogleAnalyticsV2 is a gem built for Jekyll 3 that generates statics on your Blog
+#
+# Author: z3nth10n (United Teamwork Association)
+# Site: https://github.com/uta-org/jekyll-patreon
+# Distributed Under The MIT License (MIT) as described in the LICENSE file
+#   - https://opensource.org/licenses/MIT
+
+require "jekyll-ga-v2/version"
+# Files needed in general
+require "jekyll-ga-v2/jekyll-ga-v2"
+
+module Jekyll 
+  module GoogleAnalyticsV2
+  end # module GoogleAnalyticsV2
+end # module Jekyll

data/lib/jekyll-ga-v2/jekyll-ga-v2.rb

@@ -0,0 +1,292 @@
+# Adapted from https://code.google.com/p/google-api-ruby-analytics/
+
+require 'jekyll'
+require 'rubygems'
+require 'googleauth'
+require 'google/apis/analytics_v3'
+require 'chronic'
+require 'json'
+
+module Jekyll
+
+  class GoogleAnalytics < Generator
+    priority :highest
+      
+    @response_data = nil
+    @past_response = nil
+    @headers = nil
+
+    def generate(site)    
+      unless site.config['jekyll_ga']
+        return
+      end
+        
+      Jekyll.logger.info "Jekyll GA:","Initializating"
+      startTime = Time.now
+
+      # Set "ga" to store the current config
+      ga = site.config['jekyll_ga']
+        
+      # Local cache setup so we don't hit the sever X amount of times for same data.
+      cache_directory = ga['cache_directory'] || "_jekyll_ga"
+      cache_filename = ga['cache_filename'] || "ga_cache.json"
+      cache_file_path = cache_directory + "/" + cache_filename
+
+      # Set the refresh rate in minutes (how long the program will wait in minutes before writing a new file)
+      refresh_rate = ga['refresh_rate'] || 60
+
+      # If the directory doesn't exist lets make it
+      if not Dir.exist?(cache_directory)
+        Dir.mkdir(cache_directory)
+      end
+
+      # Now lets check for the cache file and how old it is (if it exceeds refesh_rate then update it)
+      if File.exist?(cache_file_path) and ((Time.now - File.mtime(cache_file_path)) / 60 < refresh_rate) and !ga["debug"]
+        # Inject from cache  
+        data = JSON.parse(File.read(cache_file_path))  
+          
+        # Into pages...
+        site.pages.each { |page|
+            page.data["stats"] = data["page-stats"][get_identifier_for("page", page)]
+        }  
+          
+        # Into posts...
+        site.posts.docs.each { |post|
+            post.data["stats"] = data["post-stats"][get_identifier_for("post", post)]
+        } 
+          
+        # Into site...
+        site.data["stats"] = data["site-stats"] 
+        site.data["period"] = data["period"]
+        site.data["headers"] = data["headers"]
+      else
+        analytics = Google::Apis::AnalyticsV3::AnalyticsService.new
+          
+         # Load our credentials for the service account (using env vars)
+        auth = ::Google::Auth::ServiceAccountCredentials
+            .make_creds(scope: 'https://www.googleapis.com/auth/analytics')
+          
+        # Assign auth
+        analytics.authorization = auth
+          
+        # Get pages && posts from site (filtering its urls)        
+        pages = site.pages.select { |page| page.name.include? ".html" }.collect { |page| filter_url(page.dir + page.name) }
+        posts = site.posts.docs.collect { |doc| filter_url(doc.url.to_s) }
+          
+        # Concat the two arrays
+        pages.push(*posts)
+          
+        # Create a queryString (string type) from the array
+        queryString = pages.collect { |page| "ga:pagePath==#{page.to_s}" }.join(",")
+        
+        # Get the response
+        response = get_response(analytics, ga, queryString)
+          
+        # Declare the hash where the info will go  
+        store_data = {}
+        
+        # Make another request to Google Analytics API to get the pasterence
+        if ga["compare_period"]
+           start_date = Chronic.parse(ga['start']).strftime("%Y-%m-%d")
+           end_date = Chronic.parse(ga['end']).strftime("%Y-%m-%d")
+            
+           diff_date = end_date.to_date - start_date.to_date
+           diff_date = diff_date.numerator.to_i - 1
+            
+           site.data["period"] = diff_date
+           store_data.store("period", diff_date)
+            
+           @past_response = get_response(analytics, ga, queryString, start_date.to_date - diff_date, start_date) 
+        end
+
+        # If there are errors then show them
+        if response.kind_of?(Array) and response.include? "error"
+            errors = reponse["error"]["errors"]
+            
+            errors.each { |error|
+                Jekyll.logger.error "Jekyll GoogleAnalytics:", "Client Execute Error: #{error.message}"   
+            }
+            
+            raise RuntimeError, "Check errors from Google Analytics"
+        end
+
+        @response_data = response
+          
+        # Get keys from columnHeaders
+        @headers = @response_data.column_headers.collect { |header| header.name.sub("ga:", "") }
+
+        # Loop through pages && posts to add the stats object value
+        page_data = {}
+        site.pages.each { |page|
+            stats_data = get_stats_for(ga, "page", page)
+            page.data["stats"] = stats_data
+            
+            # Jekyll.logger.info "GA-debug (stats-type): ", page.data["statistics"].class.to_s
+
+            unless stats_data.nil?
+              page_data.store(get_identifier_for("page", page), stats_data)
+                
+              if ga["debug"]
+                Jekyll.logger.info "GA-debug (page-stats): ", page.data["stats"].to_json
+              end
+            end
+        }
+        store_data.store("page-stats", page_data)
+
+        post_data = {}
+        site.posts.docs.each { |post|
+            stats_data = get_stats_for(ga, "post", post)
+            post.data["stats"] = stats_data
+
+            unless stats_data.nil?
+              post_data.store(get_identifier_for("post", post), stats_data)
+                
+              if ga["debug"]
+                Jekyll.logger.info "GA-debug (post-stats): ", post.data["stats"].to_json
+              end
+            end
+        }
+        store_data.store("post-stats", post_data)
+
+        # Do the same for the site
+        stats_data = get_stats_for(ga, "site")
+        site.data["stats"] = stats_data
+          
+        store_data.store("site-stats", stats_data)
+
+        if !stats_data.nil? and ga["debug"]
+          Jekyll.logger.info "GA-debug (site-stats): ", site.data["stats"].to_json
+        end
+        
+        # Before saving modify headers
+        
+        # Create a new array with the value, the diff and the perc from the last stored stats_data corresponding to the site one
+        new_headers = []
+        @headers.each { |header|
+            unless stats_data[header].nil?            
+                protoheader = {}
+
+                protoheader.store("name", header)
+                protoheader.store("value", stats_data[header])
+                protoheader.store("diff_value", stats_data["diff_#{header}"])
+                protoheader.store("value_perc", stats_data["#{header}_perc"])
+
+                new_headers.push(protoheader)
+            end
+        }
+          
+        # Then save...  
+        site.data["headers"] = new_headers
+        store_data.store("headers", new_headers)
+
+        # Write the response data
+        if File.exist?(cache_file_path) and ((Time.now - File.mtime(cache_file_path)) / 60 >= refresh_rate) and ga["debug"] or !ga["debug"] or !File.exist?(cache_file_path)
+            File.open(cache_file_path, "w") do |f|
+              f.write(JSON.pretty_generate(store_data))
+            end
+        end
+      end
+        
+      endTime = Time.now - startTime
+
+      Jekyll.logger.info "Jekyll GoogleAnalytics:", "Initializated in #{endTime} seconds"
+    end
+      
+    def get_identifier_for(page_type, inst)
+        if page_type == "page"
+            return filter_url(inst.dir + inst.name)
+        elsif page_type == "post"
+            return filter_url(inst.url.to_s)
+        end
+    end
+      
+    def get_stats_for(ga, page_type, inst = nil)
+       data = nil
+       past_data = nil
+        
+       # Transpose array into hash using columnHeaders    
+       if page_type == "page"
+          data = @response_data.rows.select { |row| row[0] == filter_url(inst.dir + inst.name) }.collect { |row| Hash[ [@headers, row].transpose ] }[0]
+          past_data = @past_response.nil? or !@past_response.nil? and @past_response.rows.nil? ? nil : @past_response.rows.select { |row| row[0] == filter_url(inst.dir + inst.name) }.collect { |row| Hash[ [@headers, row].transpose ] }[0]
+       elsif page_type == "post"
+          data = @response_data.rows.select { |row| row[0] == filter_url(inst.url.to_s) }.collect { |row| Hash[ [@headers, row].transpose ] }[0]
+          past_data = @past_response.nil? or !@past_response.nil? and @past_response.rows.nil? ? nil : @past_response.rows.select { |row| row[0] == filter_url(inst.url.to_s) }.collect { |row| Hash[ [@headers, row].transpose ] }[0]
+       elsif page_type == "site"
+          data = get_site_data(false)
+          past_data = get_site_data(true)
+       end
+        
+       if data.nil?
+           return nil
+       end
+        
+       # Create diff_xxx and xxx_perc keys for data    
+       if ga["compare_period"]
+           pre_data = {}
+           
+           data.each { |key, value|
+                present_value = value.to_f
+
+                past_value = nil
+
+                if past_data.kind_of?(Hash)
+                   past_value = past_data.fetch(key, 0.0).to_f
+                else
+                   past_value = 0.0 
+                end
+
+                if float?(value) and float?(past_value) # Filter for pagePath (not float or integer value)
+                    # Thanks to: https://stackoverflow.com/q/31981133/3286975
+                    diff_value = present_value - past_value
+                    perc_value = present_value / past_value * 100.0
+
+                    pre_data.store("diff_#{key}", diff_value)
+                    pre_data.store("#{key}_perc", perc_value == Float::INFINITY ? "∞" : (perc_value.nan? ? "0" : perc_value.to_s))
+                end
+           }
+
+           data.merge!(pre_data)
+       end
+        
+       return data
+    end
+      
+    def get_site_data(is_past)
+        data = (is_past ? @past_response : @response_data).totals_for_all_results
+        data.keys.each { |k| data[k.sub("ga:", "")] = data[k]; data.delete(k) }
+        
+        return data;
+    end
+      
+    def get_response(analytics, ga, queryString, tstart = nil, tend = nil)
+       return analytics.get_ga_data(
+                ga['profileID'], # ids
+                tstart.nil? ? Chronic.parse(ga['start']).strftime("%Y-%m-%d") : tstart.to_s, # start_date
+                tend.nil? ? Chronic.parse(ga['end']).strftime("%Y-%m-%d") : tend.to_s,   # end_date
+                ga['metrics'],  # metrics
+                dimensions: ga['dimensions'],
+                filters: ga["filters"].to_s.empty? ? queryString : ga["filters"].to_s,
+                include_empty_rows: nil,
+                max_results: ga["max_results"].nil? ? 10000 : ga["max_results"].to_i, 
+                output: nil, 
+                sampling_level: nil, 
+                segment: ga['segment']) 
+    end
+      
+    def filter_url(url)
+        if url.include? ".html"
+          url = url.sub(".html", "")
+        end
+          
+        if url.include? "index"
+          url = url.sub("index", "")
+        end
+        
+        return url
+    end
+      
+    def float?(string)
+      true if Float(string) rescue false
+    end
+  end
+end

data/lib/jekyll-ga-v2/version.rb

@@ -0,0 +1,5 @@
+module Jekyll
+  module GoogleAnalyticsV2
+    VERSION = "1.0.0"
+  end # module GoogleAnalyticsV2
+end # module Jekyll

data/readme.md

@@ -0,0 +1,204 @@
+# jekyll-ga-v2 [![Build Status](https://travis-ci.org/uta-org/jekyll-ga-v2.svg?branch=master)](https://travis-ci.org/uta-org/jekyll-ga-v2) [![Gem Version](https://badge.fury.io/rb/jekyll-ga-v2.svg)](http://badge.fury.io/rb/jekyll-ga-v2)
+
+Requires Ruby 2.5+ and Jekyll 3.8+
+
+> A Jekyll plugin that downloads Google Analytics data and adds it to your Jekyll website. The Google Analytics metric is added to each post/page's metadata and is accessible as `page.stats`. It can be printed in a template.
+
+## Installation
+
+This plugin requires three Ruby gems:
+
+```bash
+$ sudo gem install chronic
+$ sudo gem install google-api-client
+$ sudo gem install googleauth
+```
+
+Add this line to your site's Gemfile:
+
+```ruby
+gem 'jekyll-ga-v2'
+```
+
+### Set up a service account for the Google data API
+
+- Go to https://code.google.com/apis/console/b/0/ and create a new  project. 
+- Turn on the Analytics API and accept the terms of service
+- Go to `API Access` on the left sidebar menu, create a new oauth 2.0 client ID, give your project a name, and click `next`.
+- Select Application type: `Service account`, and click `Create client ID`
+- note the private key's password. It will probably be `notasecret` unless Google changes something. You'll need to enter this value in your configuration settings.
+- Download the private key. Save this file because you can only download it once.
+- Note the `Email address` for the Service account. You'll need this for your configuration settings and in the next step.
+- Log into Google Analytics and add the service account email address as a user of your Google Analytics profile: From a report page, `Admin > select a profile > Users > New User`
+
+#### Configuration of the environment variables
+
+[GoogleAuth needs the following environment variables to work.](https://github.com/googleapis/google-auth-library-ruby#example-environment-variables)
+
+There is an easy way to implement this using CircleCI (maybe you are using similar to deploy your Jekyll website). If you're not familiar with CircleCI you'll need to read carefully this post on my blog about "[How To Use Any Jekyll Plugins on GitHub Pages with CircleCI](https://z3nth10n.github.io/en/2019/03/20/jekyll-plugin-issue-with-github-pages)".
+
+Once you implement it, you'll need to go to your [CircleCI dashboard](https://circleci.com/dashboard) search your project settings and go under "**Organization > Contexts**" and create [a new Context](https://circleci.com/docs/2.0/contexts/).
+
+Look at my website [CircleCI.yml configuration here](https://github.com/z3nth10n/z3nth10n.github.io/blob/b9f7ef42e5fce33800aab80f8eabe6868b38f8e5/circle.yml#L54). The only thing remaining is to create the appropiate Context name, and then, create the required env vars:
+
+![](https://i.gyazo.com/3ad97b8e09ee7e05b8496f1cd631affa.png)
+
+**Note:** The `GOOGLE_PRIVATE_KEY` value is the output from OpenSSL. You'll need to execute the following command to get it from the `*.p12` file:
+
+```bash
+$ openssl pkcs12 -in filename.p12 -clcerts -nodes -nocerts
+```
+
+You'll need to replace all the new lines characters by `\n`. This can be easily done with Sublime Text 3 specifying the Regex options and the replacing `\n` by `\\n`.
+ 
+## Configuration
+
+To configure `jekyll-ga-v2`, you need to specify some information about your Google Analytics service account (as set up above) and your report settings.
+
+Add the following block to your Jekyll site's `_config.yml` file:
+
+```yml
+####################
+# Google Analytics #
+####################
+
+jekyll_ga:
+  profileID: ga:<user_id>   # Profile ID 
+  start: last week          # Beginning of report
+  end: now                  # End of report
+  compare_period: true      
+  metrics: ga:pageviews     # Metrics code
+  dimensions: ga:pagePath   # Dimensions
+  segment:                  # Optional
+  filters:                  # Optional
+  sort: true                # Sort posts by this metric
+  max_results: 10000        # Number of the maximum results get by the API
+  debug: false              # Debug mode
+```
+
+* `profileID` is the specific report profile from which you want to pull data. Find it by going to the report page in Google Analytics. Look at the URL. It will look something like `https://www.google.com/analytics/web/?hl=en&pli=1#report/visitors-overview/###########p######/`. The number after the `p` at the end of the URL is your `profileID`.
+* The `start` and `end` indicate the time range of data you want to query. They are parsed using Ruby's `Chronic` gem, so you can include relative or absolute dates, such as `now`, `yesterday`, `last month`, `2 weeks ago`. See [Chronic's documentation](https://github.com/mojombo/chronic#examples) for more options.
+* The `metrics` value is what you want to measure from your Google Analytics data. Usually this will be `ga:pageviews` or `ga:visits`, but it can be any metric available in Google Analytics. Specify only one. See the [Google Analytics Query Explorer](http://ga-dev-tools.appspot.com/explorer/?csw=1) to experiment with different metrics. (Your `dimension` should always be `ga:pagePath`). I recommend you the following string `ga:pageviews,ga:bounceRate,ga:sessions,ga:users,ga:newUsers`.
+* The `segment` and `filters` keys are optional parameters for your query. See the [Google Analytics Query Explorer](http://ga-dev-tools.appspot.com/explorer/?csw=1) for a description of how to use them, or just leave them out.
+* The `sort` key can be `true` or `false`. If `true`, your posts will be sorted first by your Google Analytics metic, then chronologically as is the default. If `false` or not specified, your posts will sort as usual.
+
+New params in v2:
+
+* If `compare_period` is to true, then this will create two reports (**example:** if start is set to "last month", this will create one report from "end" to "start" and the second report its end will be at the start of the first report, with this data a comparation will be created).
+
+### Need help for examples?
+
+Look at those two HTML files I created to render my settings:
+
+```html
+<div id="genstats" class="col-md-3 align-sm-right vertical-margin order-xs-fourth col-xs-expand">
+    <box class="both-offset expand-width">
+        <p>
+            <h3>Statistics</h3>
+            <p>(last {{ site.data.period }} days)</p>
+        </p>
+
+        {% for header in site.data.headers %}
+        
+            <p>
+                {% assign hvalue = header.value | plus: 0 %}
+                {{ hvalue | round }} {{ header.name }}
+            </p>
+            <p class="sub">
+                    {% if site.jekyll_ga.compare_period %}
+                    (
+                    last {{ site.data.period }} days: 
+                    {% if header.value_perc != "∞" %}
+                        {% assign perc = header.value_perc | plus: 0 %}
+
+                        {% if perc > 0 %}
+                            <i class="fas fa-arrow-up color-green"></i>
+                        {% elsif perc == 0 %}
+                            <i class="fas fa-equals"></i>
+                        {% elsif perc < 0 %}
+                            <i class="fas fa-arrow-down color-red"></i>
+                        {% endif %}
+
+                        {{ perc | round }} % | 
+                        
+                        {% assign diff = header.diff_value %}
+                        {% if diff > 0 %}+{% endif %}
+                        {{ diff | round }} than last period
+                    {% else %}
+                    ∞ %    
+                    {% endif %}
+                    )
+                {% endif %}
+            </p>
+
+        {% endfor %}
+    </box>
+</div>
+```
+
+This displays a box with the different metrics selected in your `metrics` configuration parameter:
+
+![](https://i.gyazo.com/3105ff73fc023c5cf3506b9adcd63577.png)
+
+I use this for any post:
+
+```html
+{% if page.stats.pageviews != blank %}
+    {% assign hvalue = header.value | plus: 0 %}
+    {{ hvalue | round }} views
+                
+    {% if site.jekyll_ga.compare_period %}
+        (
+        last {{ site.data.period }} days: 
+        {% if page.stats.pageviews_perc != "∞" %}
+            {% assign perc = page.stats.pageviews_perc | plus: 0 %}
+
+            {% if perc > 0 %}
+                <i class="fas fa-arrow-up color-green"></i>
+            {% elsif perc == 0 %}
+                <i class="fas fa-equals"></i>
+            {% elsif perc < 0 %}
+                <i class="fas fa-arrow-down color-red"></i>
+            {% endif %}
+
+            {{ perc | round }} % |
+            
+            {% assign diff = page.stats.diff_pageviews %}
+            {% if diff > 0 %}+{% endif %}
+            {{ diff | round }} than last period
+        {% else %}
+        ∞ %    
+        {% endif %}
+        )
+    {% endif %}
+    .
+{% endif %}
+```
+
+It only displays `xx visits (percentage % | difference between two ranges)`.
+
+## Issues
+
+Having issues? Just report in [the issue section](/issues). **Thanks for the feedback!**
+
+## Contribute
+
+Fork this repository, make your changes and then issue a pull request. If you find bugs or have new ideas that you do not want to implement yourself, file a bug report.
+
+## Donate
+
+Become a patron, by simply clicking on this button (**very appreciated!**):
+
+[![](https://c5.patreon.com/external/logo/become_a_patron_button.png)](https://www.patreon.com/z3nth10n)
+
+... Or if you prefer an one-time donation:
+
+[![](https://www.paypalobjects.com/en_US/i/btn/btn_donateCC_LG.gif)](https://paypal.me/z3nth10n)
+
+## Copyright
+
+Copyright (c) 2019 z3nth10n (United Teamwork Association).
+
+License: MIT
+
+**Best regards.**