diff --git a/README.rst b/README.md similarity index 80% rename from README.rst rename to README.md index 393bd0d..6523c0b 100644 --- a/README.rst +++ b/README.md @@ -1,5 +1,4 @@ -CKAN Google Analytics Extension -=============================== +# CKAN Google Analytics Extension **Status:** Production @@ -8,8 +7,8 @@ CKAN Google Analytics Extension A CKAN extension that both sends tracking data to Google Analytics and retrieves statistics from Google Analytics and inserts them into CKAN pages. -Features --------- +## Features + * Puts the Google Analytics asynchronous tracking code into your page headers for basic Google Analytics page tracking. @@ -24,26 +23,22 @@ Features * Add Google Analytics Event Tracking function that can be used in any exstension to create your custom events tracking. - ``ckanext.googleanalytics.plugin._post_analytics`` + ckanext.googleanalytics.plugin._post_analytics + +## Installation -Installation ------------- 1. Install the extension as usual, e.g. (from an activated virtualenv): - :: - - $ pip install -e git+https://github.com/ckan/ckanext-googleanalytics.git#egg=ckanext-googleanalytics - $ pip install -r ckanext-googleanalytics/requirements.txt + $ pip install -e git+https://github.com/ckan/ckanext-googleanalytics.git#egg=ckanext-googleanalytics + $ pip install -r ckanext-googleanalytics/requirements.txt 2. Edit your development.ini (or similar) to provide these necessary parameters: - :: - - googleanalytics.id = UA-1010101-1 - googleanalytics.account = Account name (i.e. data.gov.uk, see top level item at https://www.google.com/analytics) - googleanalytics.username = googleaccount@gmail.com - googleanalytics.password = googlepassword + googleanalytics.id = UA-1010101-1 + googleanalytics.account = Account name (i.e. data.gov.uk, see top level item at https://www.google.com/analytics) + googleanalytics.username = googleaccount@gmail.com + googleanalytics.password = googlepassword Note that your password will probably be readable by other people; so you may want to set up a new gmail account specifically for @@ -52,22 +47,20 @@ Installation 3. Edit again your configuration ini file to activate the plugin with: - :: - - ckan.plugins = googleanalytics + ckan.plugins = googleanalytics (If there are other plugins activated, add this to the list. Each plugin should be separated with a space). 4. Finally, there are some optional configuration settings (shown here - with their default settings):: + with their default settings) - googleanalytics_resource_prefix = /downloads/ - googleanalytics.domain = auto - googleanalytics.track_events = false - googleanalytics.fields = {} - googleanalytics.enable_user_id = false - googleanalytics.download_handler = ckan.views.resource:download + googleanalytics_resource_prefix = /downloads/ + googleanalytics.domain = auto + googleanalytics.track_events = false + googleanalytics.fields = {} + googleanalytics.enable_user_id = false + googleanalytics.download_handler = ckan.views.resource:download ``resource_prefix`` is an arbitrary identifier so that we can query for downloads in Google Analytics. It can theoretically be any @@ -99,12 +92,12 @@ Installation and some of your plugins redefines `resource.download` route(ckanext-cloudstorage, for example), you can specify which function must be called instead of `ckan.views.resource:download` - via `ckanext.googleanalytics.download_handler` config variable. For ckanext-cloudstorage you can use:: + via `ckanext.googleanalytics.download_handler` config variable. For ckanext-cloudstorage you can use: - ckanext.googleanalytics.download_handler = ckanext.cloudstorage.views:download + ckanext.googleanalytics.download_handler = ckanext.cloudstorage.views:download + +# Domain Linking -Domain Linking --------------- This plugin supports cross-domain tracking using Googles' site linking feature. @@ -112,18 +105,18 @@ To use this, set the ``googleanalytics.linked_domains`` configuration option to See `Googles' documentation`_ for more information -Setting Up Statistics Retrieval from Google Analytics ------------------------------------------------------ +# Setting Up Statistics Retrieval from Google Analytics + 1. Run the following command from ``src/ckanext-googleanalytics`` to set up the required database tables (of course, altering the - ``--config`` option to point to your site config file):: + ``--config`` option to point to your site config file): - paster initdb --config=../ckan/development.ini + paster initdb --config=../ckan/development.ini 2. Optionally, add:: - googleanalytics.show_downloads = true + googleanalytics.show_downloads = true to your CKAN ini file. If ``show_downloads`` is set, a download count for resources will be displayed on individual package pages. @@ -137,7 +130,7 @@ Setting Up Statistics Retrieval from Google Analytics 6. Import Google stats by running the following command from ``src/ckanext-googleanalytics``:: - paster loadanalytics credentials.json --config=../ckan/development.ini + paster loadanalytics credentials.json --config=../ckan/development.ini (Of course, pointing config at your specific site config and credentials.json at the key file obtained from the authorization step) @@ -157,8 +150,8 @@ Setting Up Statistics Retrieval from Google Analytics remember to run it by hand, or your statistics won't get updated. -Authorization --------------- +## Authorization + Before ckanext-googleanalytics can retrieve statistics from Google Analytics, you need to set up the OAUTH details which you can do by following the `instructions `_ the outcome of which will be a file with authentication key. These steps are below for convenience: @@ -175,17 +168,16 @@ Before ckanext-googleanalytics can retrieve statistics from Google Analytics, yo 6. Find "User management" button in corresponding column. Add service account using Service account ID(email) generated in 3rd step and grant "Read" role to it. -Testing -------- +## Testing + There are some very high-level functional tests that you can run using:: - (pyenv)~/pyenv/src/ckan$ nosetests --ckan ../ckanext-googleanalytics/tests/ + (pyenv)~/pyenv/src/ckan$ nosetests --ckan ../ckanext-googleanalytics/tests/ (note -- that's run from the CKAN software root, not the extension root) -Future ------- +## Future This is a bare-bones, first release of the software. There are several directions it could take in the future.