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/ |
<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">Publisher 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>Publisher Analytics</h1> | <h1>Publisher Analytics</h1> |
<h2>The top 20 publishers</h2> | <h2>The top 20 publishers</h2> |
<form class="form-inline" action="${h.url_for(controller='ckanext.ga_report.controller:GaPublisherReport',action='index')}" method="get"> | <form class="form-inline" action="${h.url_for(controller='ckanext.ga_report.controller:GaPublisherReport',action='index')}" 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"/> |
</div> | </div> |
</form> | </form> |
<table class="table table-condensed table-bordered table-striped"> | <table class="table table-condensed table-bordered table-striped"> |
<tr> | <tr> |
<th>Publisher</th> | <th>Publisher</th> |
<th>Dataset Views</th> | <th>Dataset Views</th> |
<th>Visits</th> | <th>Visits</th> |
</tr> | </tr> |
<py:for each="publisher, views, visits in c.top_publishers"> | <py:for each="publisher, views, visits in c.top_publishers"> |
<tr> | <tr> |
<td>${h.link_to(publisher.title, h.url_for(controller='ckanext.ga_report.controller:GaPublisherReport', action='read', id=publisher.name))} | <td>${h.link_to(publisher.title, h.url_for(controller='ckanext.ga_report.controller:GaPublisherReport', action='read', id=publisher.name))} |
</td> | </td> |
<td>${views}</td> | <td>${views}</td> |
<td>${visits}</td> | <td>${visits}</td> |
</tr> | </tr> |
</py:for> | </py:for> |
</table> | </table> |
</div> | </div> |
<xi:include href="../../layout.html" /> | <xi:include href="../../layout.html" /> |
<py:def function="optional_footer"> | <py:def function="optional_footer"> |
<script type='text/javascript'> | <script type='text/javascript'> |
$('.nav-tabs li a').click(function (e) { | $('.nav-tabs li a').click(function (e) { |
e.preventDefault(); | e.preventDefault(); |
$(this).tab('show'); | $(this).tab('show'); |
}) | }) |
</script> | </script> |
</py:def> | </py:def> |
</html> | </html> |
<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">Analytics for ${g.site_title}</py:def> |
<py:match path="primarysidebar"> | |
<li class="widget-container boxed widget_text"> | |
<h4>${c.publisher.title}</h4> | |
<p> | |
The table shows the top 20 most viewed datasets belonging to ${c.publisher.title}. | |
</p> | |
<p> | |
As well as showing the number of views within ${c.month_desc}, it will also show the | |
number of visitors that viewed each dataset. | |
</p> | |
<p> | |
<p>The dataset list page for <a href="${h.url_for(controller='ckanext.dgu.controllers.publisher:PublisherController', action='read', id=c.publisher.name)}">${c.publisher.title}</a> was viewed ${c.publisher_page_views} times during ${c.month_desc}</p> | |
</p> | |
</li> | |
</py:match> | |
<div py:match="content"> | <div py:match="content"> |
<h1>Analytics for ${c.publisher.title}</h1> | <h1>Analytics for ${c.publisher.title}</h1> |
<h2>Top 20 most viewed datasets</h2> | <h2>Top 20 most viewed datasets</h2> |
<p><em>Note: this data does not include API calls</em></p> | <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='read',id=c.publisher.name)}" method="get"> | <form class="form-inline" action="${h.url_for(controller='ckanext.ga_report.controller:GaPublisherReport',action='read',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"/> |
</div> | </div> |
</form> | </form> |
<p><a href="${h.url_for(controller='ckanext.dgu.controllers.publisher:PublisherController', action='read', id=c.publisher.name)}">${c.publisher.title} dataset list</a> was viewed ${c.publisher_page_views} times in ${c.month_desc}</p> | |
<table class="table table-condensed table-bordered table-striped"> | <table class="table table-condensed table-bordered table-striped"> |
<tr> | <tr> |
<th>Dataset</th> | <th>Dataset</th> |
<th>Views</th> | <th>Views</th> |
<th>Visits</th> | <th>Visits</th> |
</tr> | </tr> |
<py:for each="package, views, visits in c.top_packages"> | <py:for each="package, views, visits in c.top_packages"> |
<tr> | <tr> |
<td>${h.link_to(package.title or package.name, h.url_for(controller='package', action='read', id=package.name))} | <td>${h.link_to(package.title or package.name, h.url_for(controller='package', action='read', id=package.name))} |
</td> | </td> |
<td>${views}</td> | <td>${views}</td> |
<td>${visits}</td> | <td>${visits}</td> |
</tr> | </tr> |
</py:for> | </py:for> |
</table> | </table> |
</div> | </div> |
<xi:include href="../../layout.html" /> | <xi:include href="../../layout.html" /> |
</html> | </html> |
<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">Site analytics</py:def> | <py:def function="page_title">Site analytics</py:def> |
<py:match path="primarysidebar"> | |
<li class="widget-container boxed widget_text"> | |
<h4>Statistics</h4> | |
<p>It is possible to <a href="${h.url_for(controller='ckanext.ga_report.controller:GaReport',action='csv',month=c.month)}">export the analytics data</a> as a CSV file, which contains all of the information for ${c.month_desc}</p> | |
</li> | |
</py:match> | |
<div py:match="content"> | <div py:match="content"> |
<h1>Site statistics</h1> | <h1>Site statistics</h1> |
<form class="form-inline" action="${h.url_for(controller='ckanext.ga_report.controller:GaReport',action='index')}" method="get"> | <form class="form-inline" action="${h.url_for(controller='ckanext.ga_report.controller:GaReport',action='index')}" 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"/> |
</div> | </div> |
</form> | </form> |
<p><a href="${h.url_for(controller='ckanext.ga_report.controller:GaReport',action='csv',month=c.month)}">Export data</a> as CSV</p> | |
<div class="tabbable"> | <div class="tabbable"> |
<ul class="nav nav-tabs"> | <ul class="nav nav-tabs"> |
<li class="active"><a href="#totals" data-toggle="tab">Totals</a></li> | <li class="active"><a href="#totals" data-toggle="tab">Totals</a></li> |
<li><a href="#browsers" data-toggle="tab">Browsers</a></li> | <li><a href="#browsers" data-toggle="tab">Browsers</a></li> |
<li><a href="#os" data-toggle="tab">Operating Systems</a></li> | <li><a href="#os" data-toggle="tab">Operating Systems</a></li> |
<li><a href="#social_networks" data-toggle="tab">Social Networks</a></li> | <li><a href="#social_networks" data-toggle="tab">Social Networks</a></li> |
<li><a href="#languages" data-toggle="tab">Languages</a></li> | <li><a href="#languages" data-toggle="tab">Languages</a></li> |
<li><a href="#country" data-toggle="tab">Country</a></li> | <li><a href="#country" data-toggle="tab">Country</a></li> |
</ul> | </ul> |
<div class="tab-content"> | <div class="tab-content"> |
<div class="tab-pane active" id="totals"> | <div class="tab-pane active" id="totals"> |
<table class="table table-condensed table-bordered table-striped"> | <table class="table table-condensed table-bordered table-striped"> |
<tr> | <tr> |
<th>Name</th> | <th>Name</th> |
<th>Value</th> | <th>Value</th> |
</tr> | </tr> |
<py:for each="name, value in c.global_totals"> | <py:for each="name, value in c.global_totals"> |
<tr> | <tr> |
<td>${name}</td> | <td>${name}</td> |
<td>${value}</td> | <td>${value}</td> |
</tr> | </tr> |
</py:for> | </py:for> |
</table> | </table> |
</div> | </div> |
<div class="tab-pane" id="browsers"> | <div class="tab-pane" id="browsers"> |
<table class="table table-condensed table-bordered table-striped"> | <table class="table table-condensed table-bordered table-striped"> |
<tr> | <tr> |
<th>Name</th> | <th>Name</th> |
<th>Value</th> | <th>Value</th> |
</tr> | </tr> |
<py:for each="name, value in c.browsers"> | <py:for each="name, value in c.browsers"> |
<tr> | <tr> |
<td>${name}</td> | <td>${name}</td> |
<td>${value}</td> | <td>${value}</td> |
</tr> | </tr> |
</py:for> | </py:for> |
</table> | </table> |
</div> | </div> |
<div class="tab-pane" id="os"> | <div class="tab-pane" id="os"> |
<table class="table table-condensed table-bordered table-striped"> | <table class="table table-condensed table-bordered table-striped"> |
<tr> | <tr> |