Did you know that you can navigate the posts by swiping left and right?
Jekyll-ga-v2 a plugin to get Google Analytics data into your site
22 Mar 2019
. Category:
jekyll-plugin
.
Comments
In this post I will explain how to use the plugin called jekyll-ga-v2. I created this plugin to be able to implement a widget that shows information that Google Analytics can offer to us.
Note: Requires Ruby 2.5+ and Jekyll 3.8+
What is this used for?
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:
$ sudo gem install chronic
$ sudo gem install google-api-client
$ sudo gem install googleauth
Add this line to your site’s Gemfile:
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 Accesson the left sidebar menu, create a new oauth 2.0 client ID, give your project a name, and clicknext. - Select Application type:
Service account, and clickCreate client ID - note the private key’s password. It will probably be
notasecretunless Google changes something. You’ll need to use this value to decrypt the PCKS12 file (later explanined). - Download the private key. Save this file because you can only download it once.
- Note the
Email addressfor 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.
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”.
Once you implement it, you’ll need to go to your CircleCI dashboard search your project settings and go under “Organization > Contexts” and create a new Context.
Look at my website CircleCI.yml configuration here. The only thing remaining is to create the appropiate Context name, and then, create the required env vars:
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:
$ 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:
####################
# 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
max_results: 10000 # Number of the maximum results get by the API
debug: false # Debug mode
-
profileIDis 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 likehttps://www.google.com/analytics/web/?hl=en&pli=1#report/visitors-overview/###########p######/. The number after thepat the end of the URL is yourprofileID. - The
startandendindicate the time range of data you want to query. They are parsed using Ruby’sChronicgem, so you can include relative or absolute dates, such asnow,yesterday,last month,2 weeks ago. See Chronic’s documentation for more options. - The
metricsvalue is what you want to measure from your Google Analytics data. Usually this will bega:pageviewsorga:visits, but it can be any metric available in Google Analytics. Specify only one. See the Google Analytics Query Explorer to experiment with different metrics. (Yourdimensionshould always bega:pagePath). I recommend you the following stringga:pageviews,ga:bounceRate,ga:sessions,ga:users,ga:newUsers. - The
segmentandfilterskeys are optional parameters for your query. See the Google Analytics Query Explorer for a description of how to use them, or just leave them out.
New params in v2:
- If
compare_periodis 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).
Do you need to automatize this?
Maybe you’re thinking that you’ll need to make a new push everytime you need to update your stats. And you’re right, but CircleCI comes here again for the rescue. All you need is to schedule a nightly build.
Here is my own implementation on my CircleCI.yml configuration, again.
nightly:
triggers:
- schedule:
cron: "0 0 * * *"
filters:
branches:
only:
- gh-pages-ci
ignore:
- master
jobs:
- build:
context: "Google Analytics Sensitive Data"
Of course, you’ll need to specify the context again.
Need help for examples?
Look at those two HTML files I created to render my settings:
<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>{% t 'stats-caption' %}</h3>
            <p>({% t 'stats_last' %} {{ site.data.period }} {% t 'stats_days' %})</p>
        </p>

        {% for header in site.data.headers %}
        
            <p>
                {% assign hvalue = header.value | plus: 0 %}
                {% assign statname = 'stats_' | append: header.name %}
                {{ hvalue | round }} {% t statname %}
            </p>
            <p class="sub">
                    {% if site.jekyll_ga.compare_period %}
                    (
                    {% t 'stats_last' %} {{ site.data.period }} {% t 'stats_days' %}: 
                    {% if header.value_perc != "∞" %}
                        {% assign perc = header.value_perc | plus: 0 %}

                        {% if header.name != "bounceRate" %}
                            {% 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 %}
                        {% else %}
                            {% if diff < 0 %}
                                <i class="fas fa-arrow-up color-green"></i>
                            {% elsif diff == 0 %}
                                <i class="fas fa-equals"></i>
                            {% elsif diff > 0 %}
                                <i class="fas fa-arrow-down color-red"></i>
                            {% endif %}
                        {% endif %}

                        {{ perc | round }} % | 
                        
                        {% assign diff = header.diff_value %}
                        {% if diff > 0 %}+{% endif %}
                        {{ diff | round }}{% if header.name == "bounceRate" %}%{% endif %} {% t 'stats_last_period' %}
                    {% else %}
                    ∞ %    
                    {% endif %}
                    )
                {% endif %}
            </p>

        {% endfor %}
    </box>
</div>
Note: Keep in mind that this snippets make use of jekyll-language-plugin, by this reason you’ll need to replace all the {% t ... %} must be replaced by its equivalents:
#########
# Stats #
#########
stats-caption: 'Statistics'
stats_pageviews: "views"
stats_bounceRate: " % bounce rate"
stats_sessions: "sessions"
stats_users: "visitors"
stats_newUsers: "new visitors"
stats_last: 'last'
stats_days: 'days'
stats_last_period: 'than last period'
This displays a box with the different metrics selected in your metrics configuration parameter:
I use this for any post:
{% 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. Thanks for the feedback!
Best regards!