Status: Production
CKAN Version: >= 2.8
A CKAN extension that both sends tracking data to Google Analytics and retrieves statistics from Google Analytics and inserts them into CKAN pages.
This is a fork (of a fork) of the original project that's been updated to reflect the evolution of Google Analytics and our needs at FjellTopp.
The major changes are:
- Drop support for Python 2.x
- Drop support for Google Analytics since it is no longer supported from July 1st 2024.
-
Puts the Google Analytics asynchronous tracking code into your page headers for basic Google Analytics page tracking.
-
Adds Google Analytics Event Tracking to resource download links, so that resource downloads will be displayed as Events in the Google Analytics reporting interface.
-
Adds Google Analytics Event Tracking to some API calls so that usage of the API can be reported on via Google Analytics.
-
Add Google Analytics Event Tracking function that can be used in any exstension to create your custom events tracking.
ckanext.googleanalytics.plugin._post_analytics
It is recommended to perform the installation from an activated virtual environment such one created by venv
or conda
:
$ pip install -e git+https://github.com/fjelltopp/ckanext-googleanalytics4.git#egg=ckanext-googleanalytics
$ pip install -r ckanext-googleanalytics4/requirements.txt
Pipenv comes with its own peculiarities, especially its Pipfile
and Pipfile.lock
files, and that's why it requires its own instructions.
Edit your Pipfile
by adding the following entries:
ckanext-googleanalytics = {editable = true, git = "https://github.com/fjelltopp/ckanext-googleanalytics4.git"}
gdata = "~=2.0"
google-api-python-client = ">=1.6.1, <1.7.0"
pyOpenSSL = ">=16.2.0"
rsa = ">=3.1.4, <=4.0"
Notice how we don't add the
#egg=
information to the url, this is to avoid running afoul of PEP 508 about theegg
fragment being a bare PIP 508 project name. See more at pypa/pip#11617.
Then lock your Pipfile
with:
$ pipenv lock
Last you can now install from your Pipfile.lock
with:
$ pipenv sync --dev
You should remove the
--dev
flag in production.
The first step is to add googleanalytics
to your list of extensions either in
your development.ini
, production.ini
or ckan.ini
.
If you are using a different extension as a storage handler besides the default provided by ckan, make sure to have
googleanalytics
before your storage handler in the list of extensions.
Google Universal Analytics was phased out completely starting July 1st, 2024 with only Google Analytics 4 (GA4) supported henceforth.
Therefore all configurations options are only applicable to GA4 unlike the original extension which still supports Universal Analytics.
In order to send analytics, in theory, you need only to specify the following:
- Your measurement ID which you can find under Admin > Data collection and modification > data stream. It should be of the form
G-XXXXXXXXXX
, that isG-
followed by 10 alphanumeric characters.
Therefore the following needs to be added to your CKAN .ini
configuration file:
googleanalytics.measurement_id = G-XXXXXXXXXX
The extension allows you to retreive the number of times particular resources have been downloaded and sums up that number to inform about the number of times to inform you how many times resources in a dataset have been downloaded.
To enable this functionility, you need the following configuration:
- Your propery ID: this can be found under Admin > Propery > Property details. This will be a 9 digits number. If no property details have been created before hand, this is the time to create one.
At this point, your configuration will look as:
googleanalytics.measurement_id = G-XXXXXXXXXX
googleanalytics.property_id = 123456789
While this extension intercepts downloads in order to send additional data to Google Analytics, you need to let the extension what your download handler to it can forward it the download request and the user can be served with the actual file to download.
The configuration for this can be as follow:
googleanalytics.download_handler = ckanext.blob_storage.blueprints:download
In this case, we have blob_storage
as our storage handler (uploads and downloads)
and downloads are handled by the function download
which can found in the file
ckanext/blob_storage/blueprints.py
. This will vary depending on which storage
handler you use.
If no storage handler is provided, the default storage handler that comes with CKAN
will be used without explicitly providing it:
googleanalytics.download_handler = ckan.views.resource:download
In order to retrieve statistics from Google Analytics, we need to enable the Google Analytics API and be able to authenticate with it every time we need data.
Some steps below require to have the gcloud
CLI installed. Details can be found at
https://cloud.google.com/sdk/docs/install.
After installing gcloud
, run gcloud init
to get gcloud
linked to your account.
This accomplished by creating a Google Cloud account at Google Cloud then following these steps:
- Create a project at https://console.cloud.google.com/projectcreate. If you have no organization, choose the
No organization
option when creating the project. - Once you have a project, you need to create a service account under that project:
$ gcloud iam service-accounts create google-analytics --description="Service account for Google analytics" --display-name="Google analytics service account"\n
- Once you have a service account, you need to create a service account key.
This will result in a JSON file being downloaded on your computer that contains
the credentials to access the service account so save it carefully:
where
$ gcloud iam service-accounts keys create google-analytics-service-account-key.json --iam-account=IAM_ACCOUNT
IAM_ACCOUNT
can be found by runninggcloud iam service-accounts list
. It will be an email-looking like string. - Enable the Google Analytics API: go to https://console.cloud.google.com/apis/dashboard?project=PROJECT_ID where
PROJECT_ID
can be obtained by runninggcloud projects list
.
With the file google-analytics-service-account-key.json
in our hands and the Google Analytics API enabled, we can proceed to pull analytics from Google Analytics.
Right now, the only analytics you can get correspond to file downloads.
- First, initialize the database by creating tables that
ckanext-googleanalytics
needs:$ ckan -c /path/to/ckan.ini googleanalytics init
- Then pull analytics into the local database:
$ ckan -c /path/to/ckan.ini googleanalytics load /path/to/google-analytics-service-account-key.json
There are some very high-level functional tests that you can run using::
(pyenv)~/pyenv/src/ckan$ nosetests --ckan ../ckanext-googleanalytics/tests/
(note -- that's run from the CKAN software root, not the extension root)
The extension is under active development. Given this fork is under the care of FjellTopp, the functionalities added will largely depend on our needs.