How to setup Analytics environment for testing
Environmental Variables
You need to set on your environment the following:
export DOT_ANALYTICS_IDP_URL=http://host.docker.internal:61111/realms/dotcms/protocol/openid-connect/token
export DOT_ANALYTICS_ACCESSTOKEN_TTL=20000
If you are using docker, you need to set them under the environment section:
// The rest of you yaml file
services:
dotcms:
image: dotcms/${DOCKER_IMAGE_TAG}
environment:
// THE REST OF YOUR ENV VARS
'DOT_ANALYTICS_IDP_URL': 'http://host.docker.internal:61111/realms/dotcms/protocol/openid-connect/token'
'DOT_ANALYTICS_ACCESSTOKEN_TTL': '20000'
// The rest of you yaml file...dotCMS Config
Now naturally run dotCMS and wait for it to be up and running.
Jump into your terminal and run the following docker-compose using:
docker compose up
Wait for it to download what it needs and run.
Go ahead to the Apps Portlet and look for Analytics App
Open the App and select the site you want to configure Analytics for. You will see a form like this:
You don’t need to fill all the fields. These are the values you need.
ClientIId: analytics-customer-customer1Client Secret: testsecret
Analytics Config URL http://host.docker.internal:8088/c/customer1/cluster1/keys
Analytics Write URL http://host.docker.internal:8081/api/v1/event
Analytics Read URL http://host.docker.internal:4001The Analytics Key field will be automatically filled by the system when it detects the config.
Go click on save.
And if you can access the Experiment Portlet inside the UVE, you should be good to go.
Note: To be sure that is properly configured, before going to the Experiment Portlet, hit save and reload until you see the Analytics Key field filled with something like this.
If a after a long time (~5 min), this is not filled, you can try replacing this environmental variable:
'DOT_ANALYTICS_IDP_URL': 'http://host.docker.internal:4001/realms/dotcms/protocol/openid-connect/token'Remember to format it accordingly with your dotCMS setup (docker or system variable). The only change was the port, from 61111 to 4001.
Another way to find if there was an error, search the port (61111 or 4001) in the terminal where you have the dedicated docker compose for Analytics running. If you set the wrong port, you will be able to find a message from cube like this:
http://host.docker.internal:61111/realms/dotcms/protocol/openid-connect/certs failed, reason: socket hang upIn this case, that means that I set the wrong port and I should be using the version with 61111 port
After you are sure about the change and replacing the environmental variable, go ahead and try again the setup.
Content Analytics API (POST v1/analytics/content/event)
This API receives a JSON in its body and uses the Analytics library to work on JS. This means that it requires some data provided by that Library or provided by us, using the clients browser information.
This is the main data we need:
{
// Random UUID generated by Analytics library, not required if authenticated
"anonymousId": "550e8400-e29b-41d4-a716-446655440000",
// Source of the event, dotAnalytics in this case
"src": "dotAnalytics",
// Current time (new Date().toISOString())
"utc_time": "2024-03-20T15:30:00.000Z",
// Timezone offset (new Date().getTimezoneOffset())
"local_tz_offset": 100,
// Pathname extracted from browser location (window.location.pathname)
"doc_path": "/example/page",
// Hostname extracted from browser location (window.location.hostname)
"doc_host": "example.com"
}
We also need to send an event_type that can change and it represents the type of the event you are tracking:
{
// For page requests
"event_type": "PAGE_REQUEST"
}
{
// For user trigger events
"event_type": "TRACK_EVENT"
}
We also need to send a key, which is provided by dotCMS and is the one filled on Analytics Key on Analytics App
{
// Not required if authenticated
"key": "js.cluster1.customer1.gd97ddz12wnol5ka8g"
}
Apart from this, you can send any data you want, so at the end the body of your request can look something like this:
{
"anonymousId": "550e8400-e29b-41d4-a716-446655440000",
"src": "dotAnalytics",
"utc_time": "2024-03-20T15:30:00.000Z",
"local_tz_offset": 100,
"doc_path": "/example/page",
"doc_host": "example.com",
"event_type": "TRACK_EVENT",
"key": "js.cluster1.customer1.gd97ddz12wnol5ka8g",
// Extra properties
"custom_event": "UVE_SWITCH_LANGUAGE",
"switched": {
"from": "en",
"to": "es"
},
"userId": "1234-5678-fghi-abcd",
"region": "US"
}
A JS Example on how you can hit the endpoint.
const options = {
server: "YOUR_DOTCMS_SERVER",
key: "THE_KEY_EXTRACTED_FROM_ANALYTICS_APP"
}
const EXAMPLE_ANALYTICS_EVENT = {
anonymousId: '550e8400-e29b-41d4-a716-446655440000',
src: 'dotAnalytics',
utc_time: '2024-03-20T15:30:00.000Z',
local_tz_offset: 100,
doc_path: '/example/page',
doc_host: 'example.com',
event_type: 'TRACK_EVENT',
key: options.key,
// Extra properties
custom_event: 'UVE_SWITCH_LANGUAGE',
switched: {
from: 'en',
to: 'es'
},
userId: '1234-5678-fghi-abcd',
region: 'US'
};
const ANALYTICS_ENDPOINT = '/api/v1/analytics/content/event';
try {
const response = await fetch(`${options.server}${ANALYTICS_ENDPOINT}`, {
method: 'POST',
headers: { 'Content-Type': 'application/json' },
body: JSON.stringify(EXAMPLE_ANALYTICS_EVENT)
});
if (!response.ok) {
console.error(`DotAnalytics: Server responded with status ${response.status}`);
return;
}
response.json().then((res) => {
// Here you should be able to handle the response
})
} catch (error) {
console.error('DotAnalytics: Error sending event:', error);
}