gitphp 0.2.9.1 :: ckanext-ga-report.git/blame

2012-10-04 11:09:27	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
2012-10-25 09:50:41	Ross Jones	29	$ pip install -e git+https://github.com/datagovuk/ckanext-ga-report.git#egg=ckanext-ga-report
2012-10-04 11:09:27	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
2012-10-09 16:16:33	Ross Jones	34	googleanalytics.account = Account name (e.g. data.gov.uk, see top level item at https://www.google.com/analytics)
2012-10-04 11:09:27	David Read	35	googleanalytics.token.filepath = ~/pyenv/token.dat
2012-11-06 10:33:54	Ross Jones	36	ga-report.period = monthly
		37	ga-report.bounce_url = /
		38
		39	The ga-report.bounce_url specifies a particular path to record the bounce rate for. Typically it is / (the home page).
2012-10-04 11:09:27	David Read	40
2012-10-10 10:51:11	Ross Jones	41	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)::
2012-10-04 11:09:27	David Read	42
		43	$ paster initdb --config=../ckan/development.ini
		44
		45	4. Enable the extension in your CKAN config file by adding it to ``ckan.plugins``::
		46
		47	ckan.plugins = ga-report
		48
		49	Problem shooting
		50	----------------
		51
2012-10-09 12:03:45	Ross Jones	52	* ``(ProgrammingError) relation "ga_url" does not exist``
		53	This means that the ``paster initdb`` step has not been run successfully. Refer to the installation instructions for this extension.
		54
		55
		56	Authorization
		57	--------------
		58
		59	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:
		60
		61	1. Visit the `Google APIs Console <https://code.google.com/apis/console>`_
		62
		63	2. Sign-in and create a project or use an existing project.
		64
		65	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.
		66
		67	4. Go to the `API Access pane <https://code.google.com/apis/console/#:access>`_
		68
		69	5. Click Create an OAuth 2.0 client ID....
		70
		71	6. Fill out the Branding Information fields and click Next.
		72
		73	7. In Client ID Settings, set Application type to Installed application.
		74
		75	8. Click Create client ID
		76
		77	9. The details you need below are Client ID, Client secret, and Redirect URIs
2012-10-09 12:17:02	Ross Jones	78
2012-10-09 12:03:45	Ross Jones	79
		80	Once you have set up your credentials.json file you can generate an oauth token file by using the
		81	following command, which will store your oauth token in a file called token.dat once you have finished
		82	giving permission in the browser::
2012-10-04 11:09:27	David Read	83
		84	$ paster getauthtoken --config=../ckan/development.ini
		85
2012-10-09 12:03:45	Ross Jones	86	Now ensure you reference the correct path to your token.dat in your CKAN config file (e.g. development.ini)::
2012-10-04 11:09:27	David Read	87
2012-10-09 12:03:45	Ross Jones	88	googleanalytics.token.filepath = ~/pyenv/token.dat
2012-10-04 11:09:27	David Read	89
2012-10-09 12:22:20	Ross Jones	90
		91	Tutorial
		92	--------
		93
		94	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::
		95
		96	$ paster loadanalytics latest --config=../ckan/development.ini
		97
		98	The value after the token file is how much data you want to retrieve, this can be
2012-10-04 11:09:27	David Read	99
		100	* all - data for all time (since 2010)
		101
		102	* latest - (default) just the 'latest' data
		103
		104	* YYYY-MM-DD - just data for all time periods going back to (and including) this date
		105
		106
		107
		108	Software Licence
		109	================
		110
		111	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).
		112
		113	OGL terms: http://www.nationalarchives.gov.uk/doc/open-government-licence/
		114