Analytics Export Service

• Introduction

• How does it work?

  • HTTP Request Format

  • File Name Format

  • Required Authentication

• How does the report look like?

• How can I get access?

• Example

Introduction

The analytics data export service allows the automated download of Interaction Analytics and Granular Analytics reports via a download link. From a technical perspective, it's a Rest API calling an export service. This allows it to be compatible with any power BI system.

Note: The analytics data export is a premium add-on feature.

How does it work?

HTTP Request Format

In order to export the analytics data, an HTTP GET request should be performed with the following format:

${serviceUrl}/download/v2/analytics/{analyticsId}/{filePrefix}

• serviceUrl = https://data-export.service.usercentrics.eu

• analyticsId = An aggregator of different Setting-IDs. The analytics ID will be provided by Usercentrics upon request.

• filePrefix = Analytics file prefix, for example "interaction-2022-01-01"

In response, you will get a JSON file, containing an array of download links which are valid for 15 minutes.
Example:

{
    "downloadUrls": [
        "https://storage.googleapis.com/analytics-raw-data-aggregation/analyticsId/file-1?auth=token",
        "https://storage.googleapis.com/analytics-raw-data-aggregation/analyticsId/file-2?auth=token"
    ]
}

Analytics file prefix format

We provide analytics for Interaction Analytics and Granular Analytics on a monthly, weekly and daily basis. The file name format varies for the different aggregation types and timespans.

Aggregation type

The aggregation type defines, which analytics you want to receive via the API. The two following options are available:

• Interaction Analytics: {Aggregation} = interaction

• Granular Analytics: {Aggregation} = granular

Frequency

Monthly Analytics

For the monthly report, you should use the first date of the month as a start date and the last date of the month as a second date.

• Format: {Aggregation}-YYYY-MM-DD-YYYY-MM-DD

• Example: interaction-2022-04-01-2022-04-30

• Availability: On the 1st of every month at around 8am UTC.

Weekly Analytics:

For the weekly report, you should use Monday as start date and Sunday as second date.

• Format: {Aggregation}-YYYY-MM-DD-YYYY-MM-DD

• Example: granular-2022-04-04-2022-04-10

• Availability: On every Monday at around 8am UTC.

Daily analytics:

For the daily report, you should use the exact date on which you want the analytics.

• Format: {Aggregation}-YYYY-MM-DD

• Example: interaction-2022-04-01

• Availability: The next day at around 8am UTC.

Required authentication

The service requires authentication to be passed either via header or query parameter:

• HTTP Header: x-api-key: 'your_key'

• Query parameter: apiKey=your_key

Your individual key will be provided by Usercentrics (see here).

How does the report look like?

Interaction Analytics Raw Data Export

An overview on the different event types for Interaction Analytics can be found here.

Granular Analytics Raw Data Export

There are two different possible values for consent:

• 0: Opt-out

• 1: Opt-in

Values for action in the raw data:

• 0: Accept All (onAcceptAllServices)

• 1: Deny All (onDenyAllServices)

• 2: Essential change: indicated service as essential that wasn�t before and vice versa (onEssentialChange)

• 3: User is visiting the website for the first time (onInitialPageLoad)

• 4: A bot script is detected or a CCPA CMP first visited or where we accept all implicitly for non EU users (onNonEURegion)

• 5: Session restored (onSessionRestored) deprecated

• 6: Tcf string change (onTcfStringChange)

• 7: Granular Accept or Granular Deny (onUpdateServices)

• 8: Mobile session restore (onMobileSessionRestore)

How can I get access to the export service?

To get access to the analytics export service, please reach out to your customer success manager or create a ticket on our service desk. Please make sure to provide the following information:

• Configurations (setting-IDs) the export should be provided for.

• Frequency of the reports: Monthly / weekly / daily.

• Aggregation type: Interaction Analytics ("interaction") and/or Granular Analytics ("granular")

After the analytics data export has been activated for you, you will receive your analyticsID and authentication credentials. You can also find a more detailed how-to-guide in our knowledge base article.

Example HTTP request

curl --location --request GET 'https://data-export.service.usercentrics.eu/download/v2/analytics/analyticsID/interaction-2022-01-01' \
--header 'X-API-Key: your_key'

curl --location --request GET 'https://data-export.service.usercentrics.eu/download/analytics/analyticsID/interaction-2022-01-01-000000000000.csv' \
--header 'X-API-Key: your_key'

To generate your HTTP request, you can use our Swagger documentation.