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/okfn/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.username = googleaccount@gmail.com | googleanalytics.account = Account name (i.e. data.gov.uk, see top level item at https://www.google.com/analytics) |
googleanalytics.password = googlepassword | |
ga-report.period = monthly | ga-report.period = monthly |
Note that your password 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 datetime | import datetime |
from pylons import config | from pylons import config |
import ga_model | import ga_model |
#from ga_client import GA | #from ga_client import GA |
log = logging.getLogger('ckanext.ga-report') | log = logging.getLogger('ckanext.ga-report') |
FORMAT_MONTH = '%Y-%m' | FORMAT_MONTH = '%Y-%m' |
class DownloadAnalytics(object): | class DownloadAnalytics(object): |
'''Downloads and stores analytics info''' | '''Downloads and stores analytics info''' |
def __init__(self, service=None, profile_id=None): | def __init__(self, service=None, profile_id=None): |
self.period = config['ga-report.period'] | self.period = config['ga-report.period'] |
self.service = service | self.service = service |
self.profile_id = profile_id | self.profile_id = profile_id |
def all_(self): | def all_(self): |
self.since_date(datetime.datetime(2010, 1, 1)) | self.since_date(datetime.datetime(2010, 1, 1)) |
def latest(self): | def latest(self): |
if self.period == 'monthly': | if self.period == 'monthly': |
# from first of this month to today | # from first of this month to today |
now = datetime.datetime.now() | now = datetime.datetime.now() |
first_of_this_month = datetime.datetime(now.year, now.month, 1) | first_of_this_month = datetime.datetime(now.year, now.month, 1) |
periods = ((now.strftime(FORMAT_MONTH), | periods = ((now.strftime(FORMAT_MONTH), |
now.day, | now.day, |
first_of_this_month, now),) | first_of_this_month, now),) |
else: | else: |
raise NotImplementedError | raise NotImplementedError |
self.download_and_store(periods) | self.download_and_store(periods) |
def since_date(self, since_date): | def since_date(self, since_date): |
assert isinstance(since_date, datetime.datetime) | assert isinstance(since_date, datetime.datetime) |
periods = [] # (period_name, period_complete_day, start_date, end_date) | periods = [] # (period_name, period_complete_day, start_date, end_date) |
if self.period == 'monthly': | if self.period == 'monthly': |
first_of_the_months_until_now = [] | first_of_the_months_until_now = [] |
year = since_date.year | year = since_date.year |
month = since_date.month | month = since_date.month |
now = datetime.datetime.now() | now = datetime.datetime.now() |
first_of_this_month = datetime.datetime(now.year, now.month, 1) | first_of_this_month = datetime.datetime(now.year, now.month, 1) |
while True: | while True: |
first_of_the_month = datetime.datetime(year, month, 1) | first_of_the_month = datetime.datetime(year, month, 1) |
if first_of_the_month == first_of_this_month: | if first_of_the_month == first_of_this_month: |
periods.append((now.strftime(FORMAT_MONTH), | periods.append((now.strftime(FORMAT_MONTH), |
now.day, | now.day, |
first_of_this_month, now)) | first_of_this_month, now)) |
break | break |
elif first_of_the_month < first_of_this_month: | elif first_of_the_month < first_of_this_month: |
in_the_next_month = first_of_the_month + datetime.timedelta(40) | in_the_next_month = first_of_the_month + datetime.timedelta(40) |
last_of_the_month = datetime.datetime(in_the_next_month.year, | last_of_the_month = datetime.datetime(in_the_next_month.year, |
in_the_next_month.month, 1)\ | in_the_next_month.month, 1)\ |
- datetime.timedelta(1) | - datetime.timedelta(1) |
periods.append((now.strftime(FORMAT_MONTH), 0, | periods.append((now.strftime(FORMAT_MONTH), 0, |
first_of_the_month, last_of_the_month)) | first_of_the_month, last_of_the_month)) |
else: | else: |
# first_of_the_month has got to the future somehow | # first_of_the_month has got to the future somehow |
break | break |
month += 1 | month += 1 |
if month > 12: | if month > 12: |
year += 1 | year += 1 |
month = 1 | month = 1 |
else: | else: |
raise NotImplementedError | raise NotImplementedError |
self.download_and_store(periods) | self.download_and_store(periods) |
@staticmethod | @staticmethod |
def get_full_period_name(period_name, period_complete_day): | def get_full_period_name(period_name, period_complete_day): |
if period_complete_day: | if period_complete_day: |
return period_name + ' (up to %ith)' % period_complete_day | return period_name + ' (up to %ith)' % period_complete_day |
else: | else: |
return period_name | return period_name |
def download_and_store(self, periods): | def download_and_store(self, periods): |
for period_name, period_complete_day, start_date, end_date in periods: | for period_name, period_complete_day, start_date, end_date in periods: |
log.info('Downloading Analytics for period "%s" (%s - %s)', | log.info('Downloading Analytics for period "%s" (%s - %s)', |
self.get_full_period_name(period_name, period_complete_day), | self.get_full_period_name(period_name, period_complete_day), |
start_date.strftime('%Y %m %d'), | start_date.strftime('%Y %m %d'), |
end_date.strftime('%Y %m %d')) | end_date.strftime('%Y %m %d')) |
data = self.download(start_date, end_date) | data = self.download(start_date, end_date) |
log.info('Storing Analytics for period "%s"', | log.info('Storing Analytics for period "%s"', |
self.get_full_period_name(period_name, period_complete_day)) | self.get_full_period_name(period_name, period_complete_day)) |
self.store(period_name, period_complete_day, data) | self.store(period_name, period_complete_day, data) |
def download(self, start_date, end_date): | def download(self, start_date, end_date): |
'''Get data from GA for a given time period''' | '''Get data from GA for a given time period''' |
start_date = start_date.strftime('%Y-%m-%d') | start_date = start_date.strftime('%Y-%m-%d') |
end_date = end_date.strftime('%Y-%m-%d') | end_date = end_date.strftime('%Y-%m-%d') |
# url | query = 'ga:pagePath=~/dataset/[a-z0-9-]+$' |
#query = 'ga:pagePath=~^%s,ga:pagePath=~^%s' % \ | |
# (PACKAGE_URL, self.resource_url_tag) | |
query = 'ga:pagePath=~^/dataset/' | |
#query = 'ga:pagePath=~^/User/' | |
metrics = 'ga:uniquePageviews' | metrics = 'ga:uniquePageviews' |
sort = '-ga:uniquePageviews' | sort = '-ga:uniquePageviews' |
# Supported query params at | # Supported query params at |
# https://developers.google.com/analytics/devguides/reporting/core/v3/reference | # https://developers.google.com/analytics/devguides/reporting/core/v3/reference |
results = self.service.data().ga().get( | results = self.service.data().ga().get( |
ids='ga:' + self.profile_id, | ids='ga:' + self.profile_id, |
filters=query, | filters=query, |
start_date=start_date, | start_date=start_date, |
metrics=metrics, | metrics=metrics, |
sort=sort, | sort=sort, |
dimensions="ga:pagePath", | |
max_results=10000, | |
end_date=end_date).execute() | end_date=end_date).execute() |
self.print_results(results) | |
# for entry in GA.ga_query(query_filter=query, | |
# from_date=start_date, | |
# metrics=metrics, | |
# sort=sort, | |
# to_date=end_date): | |
# print entry, type(entry) | |
# import pdb; pdb.set_trace() | |
# for dim in entry.dimension: | |
# if dim.name == "ga:pagePath": | |
# package = dim.value | |
# count = entry.get_metric( | |
# 'ga:uniquePageviews').value or 0 | |
# packages[package] = int(count) | |
return [] | |
def print_results(self, results): | |
import pprint | import pprint |
pprint.pprint(results) | pprint.pprint(results) |
if results: | print 'Total results: %s' % results.get('totalResults') |
print 'Profile: %s' % results.get('profileInfo').get('profileName') | |
print 'Total results: %s' % results.get('totalResults') | packages = [] |
print 'Total Visits: %s' % results.get('rows', [[-1]])[0][0] | for entry in results.get('rows'): |
else: | (loc,size,) = entry |
print 'No results found' | packages.append( ('http:/' + loc,size, '',) ) # Temporary hack |
return dict(url=packages) | |
def store(self, period_name, period_complete_day, data): | def store(self, period_name, period_complete_day, data): |
if 'url' in data: | if 'url' in data: |
ga_model.update_url_stats(period_name, period_complete_day, data['url']) | ga_model.update_url_stats(period_name, period_complete_day, data['url']) |
import os | |
import httplib2 | import httplib2 |
from apiclient.discovery import build | from apiclient.discovery import build |
from oauth2client.client import flow_from_clientsecrets | from oauth2client.client import flow_from_clientsecrets |
from oauth2client.file import Storage | from oauth2client.file import Storage |
from oauth2client.tools import run | from oauth2client.tools import run |
from pylons import config | from pylons import config |
def _prepare_credentials(token_filename, credentials_filename): | def _prepare_credentials(token_filename, credentials_filename): |
""" | """ |
Either returns the user's oauth credentials or uses the credentials | Either returns the user's oauth credentials or uses the credentials |
file to generate a token (by forcing the user to login in the browser) | file to generate a token (by forcing the user to login in the browser) |
""" | """ |
storage = Storage(token_filename) | storage = Storage(token_filename) |
credentials = storage.get() | credentials = storage.get() |
if credentials is None or credentials.invalid: | if credentials is None or credentials.invalid: |
flow = flow_from_clientsecrets(credentials_filename, | flow = flow_from_clientsecrets(credentials_filename, |
scope='https://www.googleapis.com/auth/analytics.readonly', | scope='https://www.googleapis.com/auth/analytics.readonly', |
message="Can't find the credentials file") | message="Can't find the credentials file") |
credentials = run(flow, storage) | credentials = run(flow, storage) |
return credentials | return credentials |
def init_service(token_file, credentials_file): | def init_service(token_file, credentials_file): |
""" | """ |
Given a file containing the user's oauth token (and another with | Given a file containing the user's oauth token (and another with |
credentials in case we need to generate the token) will return a | credentials in case we need to generate the token) will return a |
service object representing the analytics API. | service object representing the analytics API. |
""" | """ |
http = httplib2.Http() | http = httplib2.Http() |
credentials = _prepare_credentials(token_file, credentials_file) | credentials = _prepare_credentials(token_file, credentials_file) |
http = credentials.authorize(http) # authorize the http object | http = credentials.authorize(http) # authorize the http object |
return build('analytics', 'v3', http=http) | return build('analytics', 'v3', http=http) |
def get_profile_id(service): | def get_profile_id(service): |
""" | """ |
Get the profile ID for this user and the service specified by the | Get the profile ID for this user and the service specified by the |
'googleanalytics.id' configuration option. | 'googleanalytics.id' configuration option. This function iterates |
over all of the accounts available to the user who invoked the | |
service to find one where the account name matches (in case the | |
user has several). | |
""" | """ |
accounts = service.management().accounts().list().execute() | accounts = service.management().accounts().list().execute() |
if not accounts.get('items'): | if not accounts.get('items'): |
return None | return None |
accountId = accounts.get('items')[0].get('id') | accountName = config.get('googleanalytics.account') |
webPropertyId = config.get('googleanalytics.id') | webPropertyId = config.get('googleanalytics.id') |
for acc in accounts.get('items'): | |
if acc.get('name') == accountName: | |
accountId = acc.get('id') | |
webproperties = service.management().webproperties().list(accountId=accountId).execute() | |
profiles = service.management().profiles().list( | profiles = service.management().profiles().list( |
accountId=accountId, webPropertyId=webPropertyId).execute() | accountId=accountId, webPropertyId=webPropertyId).execute() |
if profiles.get('items'): | if profiles.get('items'): |
return profiles.get('items')[0].get('id') | return profiles.get('items')[0].get('id') |
return None | return None |