Show top datasets cross-publisher. Drop-down for the publisher. Browser version numbers filtered on download, so you get this version in the CSV too - for privacy. single_popular_dataset now copes when not much data, and can return the figures so DGU can reskin it in its own repo. Notes about usage stats centralised to notes.html.
[ckanext-ga-report.git] / README.rst
David Read 1 ckanext-ga-report
2 =================
3
4 **Status:** Development
5
6 **CKAN Version:** 1.7.1+
7
8
9 Overview
10 --------
11
12 For creating detailed reports of CKAN analytics, including totals per group.
13
14 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).
15
16 Contents of this extension:
17
18 * Use the CLI tool to download Google Analytics data for each time period into this extension's database tables
19
20 * Users can view the data as web page reports
21
22
23 Installation
24 ------------
25
26 1. Activate you CKAN python environment and install this extension's software::
27
28 $ pyenv/bin/activate
Ross Jones 29 $ pip install -e git+https://github.com/datagovuk/ckanext-ga-report.git#egg=ckanext-ga-report
David Read 30
31 2. Ensure you development.ini (or similar) contains the info about your Google Analytics account and configuration::
32
33 googleanalytics.id = UA-1010101-1
David Read 34 googleanalytics.account = Account name (e.g. data.gov.uk, see top level item at https://www.google.com/analytics)
David Read 35 ga-report.period = monthly
36
37 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)::
38
39 $ paster initdb --config=../ckan/development.ini
40
41 4. Enable the extension in your CKAN config file by adding it to ``ckan.plugins``::
42
43 ckan.plugins = ga-report
44
David Read 45 Problem shooting
46 ----------------
47
48 * ``(ProgrammingError) relation "ga_url" does not exist``
49 This means that the ``paster initdb`` step has not been run successfully. Refer to the installation instructions for this extension.
50
David Read 51
Ross Jones 52 Authorization
53 --------------
54
55 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:
56
57 1. Visit the `Google APIs Console <https://code.google.com/apis/console>`_
58
59 2. Sign-in and create a project or use an existing project.
60
61 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.
62
63 4. Go to the `API Access pane <https://code.google.com/apis/console/#:access>`_
64
65 5. Click Create an OAuth 2.0 client ID....
66
67 6. Fill out the Branding Information fields and click Next.
68
69 7. In Client ID Settings, set Application type to Installed application.
70
71 8. Click Create client ID
72
73 9. The details you need below are Client ID, Client secret, and Redirect URIs
74
75
76 Once you have set up your credentials.json file you can generate an oauth token file by using the
77 following command, which will store your oauth token in a file called token.dat once you have finished
Ross Jones 78 giving permission in the browser::
Ross Jones 79
80 $ paster getauthtoken --config=../ckan/development.ini
81
82
David Read 83 Tutorial
84 --------
85
David Read 86 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::
David Read 87
Ross Jones 88 $ paster loadanalytics token.dat latest --config=../ckan/development.ini
David Read 89
Ross Jones 90 The value after the token file is how much data you want to retrieve, this can be
91
92 * **all** - data for all time (since 2010)
93
94 * **latest** - (default) just the 'latest' data
95
96 * **YYYY-MM-DD** - just data for all time periods going back to (and including) this date
97
98
David Read 99
100 Software Licence
101 ================
102
103 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).
104
105 OGL terms: http://www.nationalarchives.gov.uk/doc/open-government-licence/
106