ckanext-ga-report | ckanext-ga-report |
================= | ================= |
**Status:** Development | **Status:** Development |
**CKAN Version:** 1.7.1+ | **CKAN Version:** 1.7.1+ |
Overview | Overview |
-------- | -------- |
For creating detailed reports of CKAN analytics, including totals per group. | For creating detailed reports of CKAN analytics, including totals per group. |
Whereas ckanext-googleanalytics focusses on providing page view stats a recent period and for all time (aimed at end users), ckanext-ga-report is more interested in building regular periodic reports (more for site managers to monitor). | Whereas ckanext-googleanalytics focusses on providing page view stats a recent period and for all time (aimed at end users), ckanext-ga-report is more interested in building regular periodic reports (more for site managers to monitor). |
Contents of this extension: | Contents of this extension: |
* Use the CLI tool to download Google Analytics data for each time period into this extension's database tables | * Use the CLI tool to download Google Analytics data for each time period into this extension's database tables |
* Users can view the data as web page reports | * Users can view the data as web page reports |
Installation | Installation |
------------ | ------------ |
1. Activate you CKAN python environment and install this extension's software:: | 1. Activate you CKAN python environment and install this extension's software:: |
$ pyenv/bin/activate | $ pyenv/bin/activate |
$ pip install -e git+https://github.com/okfn/ckanext-ga-report.git#egg=ckanext-ga-report | $ pip install -e git+https://github.com/datagovuk/ckanext-ga-report.git#egg=ckanext-ga-report |
2. Ensure you development.ini (or similar) contains the info about your Google Analytics account and configuration:: | 2. Ensure you development.ini (or similar) contains the info about your Google Analytics account and configuration:: |
googleanalytics.id = UA-1010101-1 | googleanalytics.id = UA-1010101-1 |
googleanalytics.account = Account name (i.e. data.gov.uk, see top level item at https://www.google.com/analytics) | googleanalytics.account = Account name (i.e. data.gov.uk, see top level item at https://www.google.com/analytics) |
ga-report.period = monthly | ga-report.period = monthly |
Note that your credentials will be readable by system administrators on your server. Rather than use sensitive account details, it is suggested you give access to the GA account to a new Google account that you create just for this purpose. | Note that your credentials will be readable by system administrators on your server. Rather than use sensitive account details, it is suggested you give access to the GA account to a new Google account that you create just for this purpose. |
3. Set up this extension's database tables using a paster command. (Ensure your CKAN pyenv is still activated, run the command from ``src/ckanext-ga-report``, alter the ``--config`` option to point to your site config file):: | 3. Set up this extension's database tables using a paster command. (Ensure your CKAN pyenv is still activated, run the command from ``src/ckanext-ga-report``, alter the ``--config`` option to point to your site config file):: |
$ paster initdb --config=../ckan/development.ini | $ paster initdb --config=../ckan/development.ini |
4. Enable the extension in your CKAN config file by adding it to ``ckan.plugins``:: | 4. Enable the extension in your CKAN config file by adding it to ``ckan.plugins``:: |
ckan.plugins = ga-report | ckan.plugins = ga-report |
Authorization | Authorization |
-------------- | -------------- |
Before you can access the data, you need to set up the OAUTH details which you can do by following the `instructions <https://developers.google.com/analytics/resources/tutorials/hello-analytics-api>`_ the outcome of which will be a file called credentials.json which should look like credentials.json.template with the relevant fields completed. These steps are below for convenience: | Before you can access the data, you need to set up the OAUTH details which you can do by following the `instructions <https://developers.google.com/analytics/resources/tutorials/hello-analytics-api>`_ the outcome of which will be a file called credentials.json which should look like credentials.json.template with the relevant fields completed. These steps are below for convenience: |
1. Visit the `Google APIs Console <https://code.google.com/apis/console>`_ | 1. Visit the `Google APIs Console <https://code.google.com/apis/console>`_ |
2. Sign-in and create a project or use an existing project. | 2. Sign-in and create a project or use an existing project. |
3. In the `Services pane <https://code.google.com/apis/console#:services>`_ , activate Analytics API for your project. If prompted, read and accept the terms of service. | 3. In the `Services pane <https://code.google.com/apis/console#:services>`_ , activate Analytics API for your project. If prompted, read and accept the terms of service. |
4. Go to the `API Access pane <https://code.google.com/apis/console/#:access>`_ | 4. Go to the `API Access pane <https://code.google.com/apis/console/#:access>`_ |
5. Click Create an OAuth 2.0 client ID.... | 5. Click Create an OAuth 2.0 client ID.... |
6. Fill out the Branding Information fields and click Next. | 6. Fill out the Branding Information fields and click Next. |
7. In Client ID Settings, set Application type to Installed application. | 7. In Client ID Settings, set Application type to Installed application. |
8. Click Create client ID | 8. Click Create client ID |
9. The details you need below are Client ID, Client secret, and Redirect URIs | 9. The details you need below are Client ID, Client secret, and Redirect URIs |
Once you have set up your credentials.json file you can generate an oauth token file by using the | Once you have set up your credentials.json file you can generate an oauth token file by using the |
following command, which will store your oauth token in a file called token.dat once you have finished | following command, which will store your oauth token in a file called token.dat once you have finished |
giving permission in the browser:: | giving permission in the browser:: |
$ paster getauthtoken --config=../ckan/development.ini | $ paster getauthtoken --config=../ckan/development.ini |
Tutorial | Tutorial |
-------- | -------- |
Download some GA data and store it in CKAN's db. (Ensure your CKAN pyenv is still activated, run the command from ``src/ckanext-ga-report``, alter the ``--config`` option to point to your site config file) and specifying the name of your auth file (token.dat by default) from the previous step:: | Download some GA data and store it in CKAN's db. (Ensure your CKAN pyenv is still activated, run the command from ``src/ckanext-ga-report``, alter the ``--config`` option to point to your site config file) and specifying the name of your auth file (token.dat by default) from the previous step:: |
$ paster loadanalytics token.dat latest --config=../ckan/development.ini | $ paster loadanalytics token.dat latest --config=../ckan/development.ini |
The value after the token file is how much data you want to retrieve, this can be | The value after the token file is how much data you want to retrieve, this can be |
* **all** - data for all time (since 2010) | * **all** - data for all time (since 2010) |
* **latest** - (default) just the 'latest' data | * **latest** - (default) just the 'latest' data |
* **YYYY-MM-DD** - just data for all time periods going back to (and including) this date | * **YYYY-MM-DD** - just data for all time periods going back to (and including) this date |
Software Licence | Software Licence |
================ | ================ |
This software is developed by Cabinet Office. It is Crown Copyright and opened up under the Open Government Licence (OGL) (which is compatible with Creative Commons Attibution License). | This software is developed by Cabinet Office. It is Crown Copyright and opened up under the Open Government Licence (OGL) (which is compatible with Creative Commons Attibution License). |
OGL terms: http://www.nationalarchives.gov.uk/doc/open-government-licence/ | OGL terms: http://www.nationalarchives.gov.uk/doc/open-government-licence/ |
import logging | import logging |
import operator | import operator |
from ckan.lib.base import BaseController, c, render,request | from ckan.lib.base import BaseController, c, render, request, response |
import sqlalchemy | |
from sqlalchemy import func, cast, Integer | |
import ckan.model as model | import ckan.model as model |
from ga_model import GA_Url | from ga_model import GA_Url, GA_Stat |
log = logging.getLogger('ckanext.ga-report') | log = logging.getLogger('ckanext.ga-report') |
def _get_month_name(str): | |
import calendar | |
from time import strptime | |
d = strptime('2012-10', '%Y-%m') | |
return '%s %s' % (calendar.month_name[d.tm_mon], d.tm_year) | |
def _month_details(cls): | |
months = [] | |
vals = model.Session.query(cls.period_name).distinct().all() | |
for m in vals: | |
months.append( (m[0], _get_month_name(m))) | |
return sorted(months, key=operator.itemgetter(0), reverse=True) | |
class GaReport(BaseController): | class GaReport(BaseController): |
def csv(self, month): | |
import csv | |
entries = model.Session.query(GA_Stat).\ | |
filter(GA_Stat.period_name==month).\ | |
order_by('GA_Stat.stat_name, GA_Stat.key').all() | |
response.headers['Content-disposition'] = 'attachment; filename=dgu_analytics_%s.csv' % (month) | |
response.headers['Content-Type'] = "text/csv; charset=utf-8" | |
writer = csv.writer(response) | |
writer.writerow(["Period", "Statistic", "Key", "Value"]) | |
for entry in entries: | |
writer.writerow([entry.period_name.encode('utf-8'), | |
entry.stat_name.encode('utf-8'), | |
entry.key.encode('utf-8'), | |
entry.value.encode('utf-8')]) | |
def index(self): | def index(self): |
# Get the month details by fetching distinct values and determining the | |
# month names from the values. | |
c.months = _month_details(GA_Stat) | |
# Work out which month to show, based on query params of the first item | |
c.month = request.params.get('month', c.months[0][0] if c.months else '') | |
c.month_desc = ''.join([m[1] for m in c.months if m[0]==c.month]) | |
entries = model.Session.query(GA_Stat).\ | |
filter(GA_Stat.stat_name=='Totals').\ | |
filter(GA_Stat.period_name==c.month).all() | |
c.global_totals = [(s.key, s.value) for s in entries ] | |
keys = { | |
'Browser versions': 'browsers', | |
'Operating Systems versions': 'os', | |
'Social sources': 'social_networks', | |
'Languages': 'languages', | |
'Country': 'country' | |
} | |
for k, v in keys.iteritems(): | |
entries = model.Session.query(GA_Stat).\ | |
filter(GA_Stat.stat_name==k).\ | |
filter(GA_Stat.period_name==c.month).\ | |
order_by('ga_stat.value::int desc').all() | |
setattr(c, v, [(s.key, s.value) for s in entries ]) | |
return render('ga_report/site/index.html') | return render('ga_report/site/index.html') |
class GaPublisherReport(BaseController): | class GaPublisherReport(BaseController): |
""" | """ |
Displays the pageview and visit count for specific publishers based on | Displays the pageview and visit count for specific publishers based on |
the datasets associated with the publisher. | the datasets associated with the publisher. |
""" | """ |
def _get_month_name(self, str): | def index(self): |
import calendar | # Get the month details by fetching distinct values and determining the |
from time import strptime | # month names from the values. |
d = strptime('2012-10', '%Y-%m') | c.months = _month_details(GA_Url) |
return '%s %s' % (calendar.month_name[d.tm_mon], d.tm_year) | |
# Work out which month to show, based on query params of the first item | |
c.month = request.params.get('month', c.months[0][0] if c.months else '') | |
c.month_desc = ''.join([m[1] for m in c.months if m[0]==c.month]) | |
connection = model.Session.connection() | |
q = """ | |
select department_id, sum(pageviews::int) views, sum(visitors::int) visits | |
from ga_url | |
where department_id <> '' | |
and not url like '/publisher/%%' | |
and period_name=%s | |
group by department_id order by views desc limit 20; | |
""" | |
c.top_publishers = [] | |
res = connection.execute(q, c.month) | |
for row in res: | |
c.top_publishers.append((model.Group.get(row[0]), row[1], row[2])) | |
return render('ga_report/publisher/index.html') | |
def index(self, id): | def read(self, id): |
c.publisher = model.Group.get(id) | c.publisher = model.Group.get(id) |
c.top_packages = [] # package, dataset_views in c.top_packages | c.top_packages = [] # package, dataset_views in c.top_packages |
# Get the month details by fetching distinct values and determining the | # Get the month details by fetching distinct values and determining the |
# month names from the values. | # month names from the values. |
c.months = [] | c.months = _month_details(GA_Url) |
vals = model.Session.query(GA_Url.period_name).distinct().all() | |
for m in vals: | |
c.months.append( (m[0],self._get_month_name(m))) | |
# Sort the months, so most recent is at the head of our list | |
c.months = sorted(c.months, key=operator.itemgetter(0), reverse=True) | |
# Work out which month to show, based on query params of the first item | # Work out which month to show, based on query params of the first item |
c.month = request.params.get('month', c.months[0][0] if c.months else '') | c.month = request.params.get('month', c.months[0][0] if c.months else '') |
c.month_desc = ''.join([m[1] for m in c.months if m[0]==c.month]) | c.month_desc = ''.join([m[1] for m in c.months if m[0]==c.month]) |
entry = model.Session.query(GA_Url).\ | entry = model.Session.query(GA_Url).\ |
filter(GA_Url.url=='/publisher/%s' % c.publisher.name).\ | filter(GA_Url.url=='/publisher/%s' % c.publisher.name).\ |
filter(GA_Url.period_name==c.month).first() | filter(GA_Url.period_name==c.month).first() |
c.publisher_page_views = entry.pageviews if entry else 0 | c.publisher_page_views = entry.pageviews if entry else 0 |
entries = model.Session.query(GA_Url).\ | entries = model.Session.query(GA_Url).\ |
filter(GA_Url.department_id==c.publisher.name).\ | filter(GA_Url.department_id==c.publisher.name).\ |
filter(GA_Url.period_name==c.month).\ | filter(GA_Url.period_name==c.month).\ |
order_by('ga_url.pageviews desc')[:10] | order_by('ga_url.pageviews::int desc')[:20] |
for entry in entries: | for entry in entries: |
if entry.url.startswith('/dataset/'): | if entry.url.startswith('/dataset/'): |
p = model.Package.get(entry.url[len('/dataset/'):]) | p = model.Package.get(entry.url[len('/dataset/'):]) |
c.top_packages.append((p,entry.pageviews,entry.visitors)) | c.top_packages.append((p,entry.pageviews,entry.visitors)) |
return render('ga_report/publisher/index.html') | return render('ga_report/publisher/read.html') |
import logging | import logging |
import ckan.lib.helpers as h | import ckan.lib.helpers as h |
import ckan.plugins as p | import ckan.plugins as p |
from ckan.plugins import implements, toolkit | from ckan.plugins import implements, toolkit |
#import gasnippet | #import gasnippet |
#import commands | #import commands |
#import dbutil | #import dbutil |
log = logging.getLogger('ckanext.ga-report') | log = logging.getLogger('ckanext.ga-report') |
class GAReportPlugin(p.SingletonPlugin): | class GAReportPlugin(p.SingletonPlugin): |
implements(p.IConfigurer, inherit=True) | implements(p.IConfigurer, inherit=True) |
implements(p.IRoutes, inherit=True) | implements(p.IRoutes, inherit=True) |
def update_config(self, config): | def update_config(self, config): |
toolkit.add_template_directory(config, 'templates') | toolkit.add_template_directory(config, 'templates') |
toolkit.add_public_directory(config, 'public') | toolkit.add_public_directory(config, 'public') |
def after_map(self, map): | def after_map(self, map): |
map.connect( | map.connect( |
'/data/analytics/', | '/data/analytics', |
controller='ckanext.ga_report.controller:GaReport', | controller='ckanext.ga_report.controller:GaReport', |
action='index' | |
) | |
map.connect( | |
'/data/analytics_{month}.csv', | |
controller='ckanext.ga_report.controller:GaReport', | |
action='csv' | |
) | |
map.connect( | |
'/data/analytics/publisher/', | |
controller='ckanext.ga_report.controller:GaPublisherReport', | |
action='index' | action='index' |
) | ) |
map.connect( | map.connect( |
'/data/analytics/publisher/{id}', | '/data/analytics/publisher/{id}', |
controller='ckanext.ga_report.controller:GaPublisherReport', | controller='ckanext.ga_report.controller:GaPublisherReport', |
action='index' | action='read' |
) | ) |
return map | return map |
<html xmlns:py="http://genshi.edgewall.org/" | <html xmlns:py="http://genshi.edgewall.org/" |
xmlns:i18n="http://genshi.edgewall.org/i18n" | xmlns:i18n="http://genshi.edgewall.org/i18n" |
xmlns:xi="http://www.w3.org/2001/XInclude" | xmlns:xi="http://www.w3.org/2001/XInclude" |
py:strip=""> | py:strip=""> |
<py:def function="page_title">Analytics for ${g.site_title}</py:def> | <py:def function="page_title">Publisher Analytics for ${g.site_title}</py:def> |
<py:match path="primarysidebar"> | |
<li class="widget-container boxed widget_text"> | |
<h4>Publishers</h4> | |
</li> | |
</py:match> | |
<div py:match="content"> | <div py:match="content"> |
<h1>Analytics for ${c.publisher.title}</h1> | <h1>Publisher Analytics</h1> |
<h2>The top 20 publishers</h2> | |
<h2>Most viewed datasets</h2> | <form class="form-inline" action="${h.url_for(controller='ckanext.ga_report.controller:GaPublisherReport',action='index')}" method="get"> |
<p><em>Note: this data does not include API calls</em></p> | |
<form class="form-inline" action="${h.url_for(controller='ckanext.ga_report.controller:GaPublisherReport',action='index',id=c.publisher.name)}" method="get"> | |
<div class="controls"> | <div class="controls"> |
<select name="month"> | <select name="month"> |
<py:for each="val,desc in c.months"> | <py:for each="val,desc in c.months"> |
<option value='${val}' py:attrs="{'selected': 'selected' if c.month == val else None}">${desc}</option> | <option value='${val}' py:attrs="{'selected': 'selected' if c.month == val else None}">${desc}</option> |
</py:for> | </py:for> |
</select> | </select> |
<input class="btn button" type='submit' value="Update"/> | <input class="btn button" type='submit' value="Update"/> |