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/datagovuk/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 (e.g. data.gov.uk, see top level item at https://www.google.com/analytics) | googleanalytics.account = Account name (e.g. data.gov.uk, see top level item at https://www.google.com/analytics) |
googleanalytics.token.filepath = ~/pyenv/token.dat | |
ga-report.period = monthly | ga-report.period = monthly |
ga-report.bounce_url = / | ga-report.bounce_url = / |
The ga-report.bounce_url specifies a particular path to record the bounce rate for. Typically it is / (the home page). | The ga-report.bounce_url specifies a particular path to record the bounce rate for. Typically it is / (the home page). |
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 |
Problem shooting | Problem shooting |
---------------- | ---------------- |
* ``(ProgrammingError) relation "ga_url" does not exist`` | * ``(ProgrammingError) relation "ga_url" does not exist`` |
This means that the ``paster initdb`` step has not been run successfully. Refer to the installation instructions for this extension. | This means that the ``paster initdb`` step has not been run successfully. Refer to the installation instructions for this extension. |
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 |
Now ensure you reference the correct path to your token.dat in your CKAN config file (e.g. development.ini):: | |
googleanalytics.token.filepath = ~/pyenv/token.dat | |
Tutorial | Tutorial |
-------- | -------- |
Download some GA data and store it in CKAN's database. (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 database. (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 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 datetime | import datetime |
import os | |
from pylons import config | |
from ckan.lib.cli import CkanCommand | from ckan.lib.cli import CkanCommand |
# No other CKAN imports allowed until _load_config is run, | # No other CKAN imports allowed until _load_config is run, |
# or logging is disabled | # or logging is disabled |
class InitDB(CkanCommand): | class InitDB(CkanCommand): |
"""Initialise the extension's database tables | """Initialise the extension's database tables |
""" | """ |
summary = __doc__.split('\n')[0] | summary = __doc__.split('\n')[0] |
usage = __doc__ | usage = __doc__ |
max_args = 0 | max_args = 0 |
min_args = 0 | min_args = 0 |
def command(self): | def command(self): |
self._load_config() | self._load_config() |
import ckan.model as model | import ckan.model as model |
model.Session.remove() | model.Session.remove() |
model.Session.configure(bind=model.meta.engine) | model.Session.configure(bind=model.meta.engine) |
log = logging.getLogger('ckanext.ga-report') | log = logging.getLogger('ckanext.ga-report') |
import ga_model | import ga_model |
ga_model.init_tables() | ga_model.init_tables() |
log.info("DB tables are setup") | log.info("DB tables are setup") |
class GetAuthToken(CkanCommand): | class GetAuthToken(CkanCommand): |
""" Get's the Google auth token | """ Get's the Google auth token |
Usage: paster getauthtoken <credentials_file> | Usage: paster getauthtoken <credentials_file> |
Where <credentials_file> is the file name containing the details | Where <credentials_file> is the file name containing the details |
for the service (obtained from https://code.google.com/apis/console). | for the service (obtained from https://code.google.com/apis/console). |
By default this is set to credentials.json | By default this is set to credentials.json |
""" | """ |
summary = __doc__.split('\n')[0] | summary = __doc__.split('\n')[0] |
usage = __doc__ | usage = __doc__ |
max_args = 0 | max_args = 0 |
min_args = 0 | min_args = 0 |
def command(self): | def command(self): |
""" | """ |
In this case we don't want a valid service, but rather just to | In this case we don't want a valid service, but rather just to |
force the user through the auth flow. We allow this to complete to | force the user through the auth flow. We allow this to complete to |
act as a form of verification instead of just getting the token and | act as a form of verification instead of just getting the token and |
assuming it is correct. | assuming it is correct. |
""" | """ |
from ga_auth import init_service | from ga_auth import init_service |
init_service('token.dat', | init_service('token.dat', |
self.args[0] if self.args | self.args[0] if self.args |
else 'credentials.json') | else 'credentials.json') |
class LoadAnalytics(CkanCommand): | class LoadAnalytics(CkanCommand): |
"""Get data from Google Analytics API and save it | """Get data from Google Analytics API and save it |
in the ga_model | in the ga_model |
Usage: paster loadanalytics <tokenfile> <time-period> | Usage: paster loadanalytics <time-period> |
Where <tokenfile> is the name of the auth token file from | Where <time-period> is: |
the getauthtoken step. | |
And where <time-period> is: | |
all - data for all time | all - data for all time |
latest - (default) just the 'latest' data | latest - (default) just the 'latest' data |
YYYY-MM - just data for the specific month | YYYY-MM - just data for the specific month |
""" | """ |
summary = __doc__.split('\n')[0] | summary = __doc__.split('\n')[0] |
usage = __doc__ | usage = __doc__ |
max_args = 2 | max_args = 1 |
min_args = 1 | min_args = 0 |
def __init__(self, name): | def __init__(self, name): |
super(LoadAnalytics, self).__init__(name) | super(LoadAnalytics, self).__init__(name) |
self.parser.add_option('-d', '--delete-first', | self.parser.add_option('-d', '--delete-first', |
action='store_true', | action='store_true', |
default=False, | default=False, |
dest='delete_first', | dest='delete_first', |
help='Delete data for the period first') | help='Delete data for the period first') |
self.parser.add_option('-s', '--skip_url_stats', | self.parser.add_option('-s', '--skip_url_stats', |
action='store_true', | action='store_true', |
default=False, | default=False, |
dest='skip_url_stats', | dest='skip_url_stats', |
help='Skip the download of URL data - just do site-wide stats') | help='Skip the download of URL data - just do site-wide stats') |
def command(self): | def command(self): |
self._load_config() | self._load_config() |
from download_analytics import DownloadAnalytics | from download_analytics import DownloadAnalytics |
from ga_auth import (init_service, get_profile_id) | from ga_auth import (init_service, get_profile_id) |
ga_token_filepath = os.path.expanduser(config.get('googleanalytics.token.filepath', '')) | |
if not ga_token_filepath: | |
print 'ERROR: In the CKAN config you need to specify the filepath of the ' \ | |
'Google Analytics token file under key: googleanalytics.token.filepath' | |
return | |
try: | try: |
svc = init_service(self.args[0], None) | svc = init_service(ga_token_filepath, None) |
except TypeError: | except TypeError: |
print ('Have you correctly run the getauthtoken task and ' | print ('Have you correctly run the getauthtoken task and ' |
'specified the correct token file?') | 'specified the correct token file in the CKAN config under ' |
'"googleanalytics.token.filepath"?') | |
return | return |
downloader = DownloadAnalytics(svc, profile_id=get_profile_id(svc), | downloader = DownloadAnalytics(svc, profile_id=get_profile_id(svc), |
delete_first=self.options.delete_first, | delete_first=self.options.delete_first, |
skip_url_stats=self.options.skip_url_stats) | skip_url_stats=self.options.skip_url_stats) |
time_period = self.args[1] if self.args and len(self.args) > 1 \ | time_period = self.args[0] if self.args else 'latest' |
else 'latest' | |
if time_period == 'all': | if time_period == 'all': |
downloader.all_() | downloader.all_() |
elif time_period == 'latest': | elif time_period == 'latest': |
downloader.latest() | downloader.latest() |
else: | else: |
# The month to use | # The month to use |
for_date = datetime.datetime.strptime(time_period, '%Y-%m') | for_date = datetime.datetime.strptime(time_period, '%Y-%m') |
downloader.specific_month(for_date) | downloader.specific_month(for_date) |
import logging | import logging |
import operator | import operator |
import ckan.lib.base as base | import ckan.lib.base as base |
import ckan.model as model | import ckan.model as model |
from ckan.logic import get_action | from ckan.logic import get_action |
from ckanext.ga_report.ga_model import GA_Url, GA_Publisher | from ckanext.ga_report.ga_model import GA_Url, GA_Publisher |
from ckanext.ga_report.controller import _get_publishers | from ckanext.ga_report.controller import _get_publishers |
_log = logging.getLogger(__name__) | _log = logging.getLogger(__name__) |
def popular_datasets(count=10): | def popular_datasets(count=10): |
import random | import random |
publisher = None | publisher = None |
publishers = _get_publishers(30) | publishers = _get_publishers(30) |
total = len(publishers) | total = len(publishers) |
while not publisher or not datasets: | while not publisher or not datasets: |
rand = random.randrange(0, total) | rand = random.randrange(0, total) |
publisher = publishers[rand][0] | publisher = publishers[rand][0] |
if not publisher.state == 'active': | if not publisher.state == 'active': |
publisher = None | publisher = None |
continue | continue |
datasets = _datasets_for_publisher(publisher, 10)[:count] | datasets = _datasets_for_publisher(publisher, 10)[:count] |
ctx = { | ctx = { |
'datasets': datasets, | 'datasets': datasets, |
'publisher': publisher | 'publisher': publisher |
} | } |
return base.render_snippet('ga_report/ga_popular_datasets.html', **ctx) | return base.render_snippet('ga_report/ga_popular_datasets.html', **ctx) |
def single_popular_dataset(top=20): | def single_popular_dataset(top=20): |
'''Returns a random dataset from the most popular ones. | '''Returns a random dataset from the most popular ones. |
:param top: the number of top datasets to select from | :param top: the number of top datasets to select from |
''' | ''' |
import random | import random |
top_datasets = model.Session.query(GA_Url).\ | top_datasets = model.Session.query(GA_Url).\ |
filter(GA_Url.url.like('/dataset/%')).\ | filter(GA_Url.url.like('/dataset/%')).\ |
order_by('ga_url.pageviews::int desc') | order_by('ga_url.pageviews::int desc') |
num_top_datasets = top_datasets.count() | num_top_datasets = top_datasets.count() |
dataset = None | dataset = None |
if num_top_datasets: | if num_top_datasets: |
count = 0 | count = 0 |
while not dataset: | while not dataset: |
rand = random.randrange(0, min(top, num_top_datasets)) | rand = random.randrange(0, min(top, num_top_datasets)) |
ga_url = top_datasets[rand] | ga_url = top_datasets[rand] |
dataset = model.Package.get(ga_url.url[len('/dataset/'):]) | dataset = model.Package.get(ga_url.url[len('/dataset/'):]) |
if dataset and not dataset.state == 'active': | if dataset and not dataset.state == 'active': |
dataset = None | dataset = None |
count += 1 | # When testing, it is possible that top datasets are not available |
if count > 10: | # so only go round this loop a few times before falling back on |
break | # a random dataset. |
count += 1 | |
if count > 10: | |
break | |
if not dataset: | if not dataset: |
# fallback | # fallback |
dataset = model.Session.query(model.Package)\ | dataset = model.Session.query(model.Package)\ |
.filter_by(state='active').first() | .filter_by(state='active').first() |
if not dataset: | if not dataset: |
return None | return None |
dataset_dict = get_action('package_show')({'model': model, | dataset_dict = get_action('package_show')({'model': model, |
'session': model.Session, | 'session': model.Session, |
'validate': False}, | 'validate': False}, |
{'id':dataset.id}) | {'id':dataset.id}) |
return dataset_dict | return dataset_dict |
def single_popular_dataset_html(top=20): | def single_popular_dataset_html(top=20): |
dataset_dict = single_popular_dataset(top) | dataset_dict = single_popular_dataset(top) |
groups = package.get('groups', []) | groups = package.get('groups', []) |
publishers = [ g for g in groups if g.get('type') == 'publisher' ] | publishers = [ g for g in groups if g.get('type') == 'publisher' ] |
publisher = publishers[0] if publishers else {'name':'', 'title': ''} | publisher = publishers[0] if publishers else {'name':'', 'title': ''} |
context = { | context = { |
'dataset': dataset_dict, | 'dataset': dataset_dict, |
'publisher': publisher_dict | 'publisher': publisher_dict |
} | } |
return base.render_snippet('ga_report/ga_popular_single.html', **context) | return base.render_snippet('ga_report/ga_popular_single.html', **context) |
def most_popular_datasets(publisher, count=20): | def most_popular_datasets(publisher, count=20): |
if not publisher: | if not publisher: |
_log.error("No valid publisher passed to 'most_popular_datasets'") | _log.error("No valid publisher passed to 'most_popular_datasets'") |
return "" | return "" |
results = _datasets_for_publisher(publisher, count) | results = _datasets_for_publisher(publisher, count) |
ctx = { | ctx = { |
'dataset_count': len(results), | 'dataset_count': len(results), |
'datasets': results, | 'datasets': results, |
'publisher': publisher | 'publisher': publisher |
} | } |
return base.render_snippet('ga_report/publisher/popular.html', **ctx) | return base.render_snippet('ga_report/publisher/popular.html', **ctx) |
def _datasets_for_publisher(publisher, count): | def _datasets_for_publisher(publisher, count): |
datasets = {} | datasets = {} |
entries = model.Session.query(GA_Url).\ | entries = model.Session.query(GA_Url).\ |
filter(GA_Url.department_id==publisher.name).\ | filter(GA_Url.department_id==publisher.name).\ |
filter(GA_Url.url.like('/dataset/%')).\ | filter(GA_Url.url.like('/dataset/%')).\ |
order_by('ga_url.pageviews::int desc').all() | order_by('ga_url.pageviews::int desc').all() |
for entry in entries: | for entry in entries: |
if len(datasets) < count: | if len(datasets) < count: |
p = model.Package.get(entry.url[len('/dataset/'):]) | p = model.Package.get(entry.url[len('/dataset/'):]) |
if not p in datasets: | if not p in datasets: |
datasets[p] = {'views':0, 'visits': 0} | datasets[p] = {'views':0, 'visits': 0} |
datasets[p]['views'] = datasets[p]['views'] + int(entry.pageviews) | datasets[p]['views'] = datasets[p]['views'] + int(entry.pageviews) |
datasets[p]['visits'] = datasets[p]['visits'] + int(entry.visits) | datasets[p]['visits'] = datasets[p]['visits'] + int(entry.visits) |
results = [] | results = [] |
for k, v in datasets.iteritems(): | for k, v in datasets.iteritems(): |
results.append((k,v['views'],v['visits'])) | results.append((k,v['views'],v['visits'])) |
return sorted(results, key=operator.itemgetter(1), reverse=True) | return sorted(results, key=operator.itemgetter(1), reverse=True) |