| 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) |
| ga-report.period = monthly | ga-report.period = monthly |
| ga-report.bounce_url = /data | ga-report.bounce_url = / |
| The ga-report.bounce_url specifies the path to use when calculating bounces. For DGU this is /data | The ga-report.bounce_url specifies a particular path to record the bounce rate for. Typically it is / (the home page). |
| but you may want to set this to /. | |
| 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 |
| 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 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 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 <tokenfile> <time-period> |
| Where <tokenfile> is the name of the auth token file from | Where <tokenfile> is the name of the auth token file from |
| the getauthtoken step. | the getauthtoken step. |
| And where <time-period> is: | 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 = 2 |
| min_args = 1 | min_args = 1 |
| 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', '--slip_url_stats', | |
| action='store_true', | |
| default=False, | |
| dest='skip_url_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) |
| try: | try: |
| svc = init_service(self.args[0], None) | svc = init_service(self.args[0], 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?') |
| 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) | |
| time_period = self.args[1] if self.args and len(self.args) > 1 \ | time_period = self.args[1] if self.args and len(self.args) > 1 \ |
| 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 os | import os |
| import logging | import logging |
| import datetime | import datetime |
| import collections | import collections |
| from pylons import config | from pylons import config |
| from ga_model import _normalize_url | from ga_model import _normalize_url |
| 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' |
| MIN_VIEWS = 50 | MIN_VIEWS = 50 |
| MIN_VISITS = 20 | MIN_VISITS = 20 |
| class DownloadAnalytics(object): | class DownloadAnalytics(object): |
| '''Downloads and stores analytics info''' | '''Downloads and stores analytics info''' |
| def __init__(self, service=None, profile_id=None, delete_first=False): | def __init__(self, service=None, profile_id=None, delete_first=False, |
| skip_url_stats=False): | |
| 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 |
| self.delete_first = delete_first | self.delete_first = delete_first |
| self.skip_url_stats = skip_url_stats | |
| def specific_month(self, date): | def specific_month(self, date): |
| import calendar | import calendar |
| first_of_this_month = datetime.datetime(date.year, date.month, 1) | first_of_this_month = datetime.datetime(date.year, date.month, 1) |
| _, last_day_of_month = calendar.monthrange(int(date.year), int(date.month)) | _, last_day_of_month = calendar.monthrange(int(date.year), int(date.month)) |
| last_of_this_month = datetime.datetime(date.year, date.month, last_day_of_month) | last_of_this_month = datetime.datetime(date.year, date.month, last_day_of_month) |
| periods = ((date.strftime(FORMAT_MONTH), | periods = ((date.strftime(FORMAT_MONTH), |
| last_day_of_month, | last_day_of_month, |
| first_of_this_month, last_of_this_month),) | first_of_this_month, last_of_this_month),) |
| self.download_and_store(periods) | self.download_and_store(periods) |
| 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 for_date(self, for_date): | def for_date(self, for_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 = for_date.year | year = for_date.year |
| month = for_date.month | month = for_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('Period "%s" (%s - %s)', | log.info('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')) |
| if self.delete_first: | if self.delete_first: |
| log.info('Deleting existing Analytics for this period "%s"', | log.info('Deleting existing Analytics for this period "%s"', |
| period_name) | period_name) |
| ga_model.delete(period_name |