diff --git a/.env.dist b/.env.dist index e46a6fc3..e7a4cb47 100644 --- a/.env.dist +++ b/.env.dist @@ -1,70 +1,42 @@ -######################################################################################################################## -# Environment Variables - -# APP_DEBUG=1 -# APP_DEBUG_COOKIE_SECRET=value - -# COOKIE_SECURE=1 # True for sending secure flag (https) -# PROJECT_URL=https://www.example.com -# PROJECT_INTERNAL_URL=https://www.example.com # Not required, the PROJECT_URL is used if this variable is not defined -# PROJECT_API_URL=https://amp-api.example.com # Not required, the PROJECT_URL is used if this variable is not defined -# TRUSTED_PROXIES=127.0.0.1 # Not required, IP or IPs separated by a comma. The range you can enter like 1.0.0.0/1 -# SUPPORT_EMAIL=support@68publishers.io -# MAILER_EMAIL=info@68publishers.io -# MAILER_FROM="Consent Management Platform" - -# RECAPTCHA_ENABLED=1 -# GOOGLE_RECAPTCHA_SITE_KEY=site-key -# GOOGLE_RECAPTCHA_SECRET_KEY=secret-key - -# DB_HOST=server -# DB_PORT=port -# DB_NAME=dbname -# DB_USER=user -# DB_PASSWORD=password - -# REDIS_HOST=server -# REDIS_PORT=port -# REDIS_AUTH="" # optional -# REDIS_DB_CACHE=0 # optional -# REDIS_DB_SESSIONS=1 # optional - -# SMTP_ENABLED=1 -# SMTP_HOST=hostname -# SMTP_PORT=port -# SMTP_USERNAME=username -# SMTP_PASSWORD=password -# SMTP_SECURE=ssl # ssl or tls - -# SENTRY_DSN=https://hash@sentry.io/project-id -# GTM_CONTAINER_ID=GTM-XXXXXX # optional -# API_DOCS_ENABLED=1 # optional -# GRID_COUNT_LIMIT=100000 # optional -######################################################################################################################## - +# ========== Application environment ========== # APP_DEBUG=1 -APP_DEBUG_COOKIE_SECRET=idontgiveabuck07 - -COOKIE_SECURE=0 +APP_DEBUG_COOKIE_SECRET=hey_tracy PROJECT_URL=http://localhost:8888 -PROJECT_INTERNAL_URL=http://localhost:8080 -SUPPORT_EMAIL=support@68publishers.io -MAILER_EMAIL=info@68publishers.io -MAILER_FROM="Consent Management Platform" - -RECAPTCHA_ENABLED=0 +# TRUSTED_PROXIES=127.0.0.1 # Not required, IP or IPs separated by a comma. The range you can enter like 1.0.0.0/1 +COOKIE_SECURE=0 +# COOKIE_SECURE=1 # For sending secure flag (https) +API_DOCS_ENABLED=1 +GRID_COUNT_LIMIT=100000 +# GTM_CONTAINER_ID=GTM-XXXXXX # optional +# ========== PostgreSQL database ========== # DB_HOST=db DB_PORT=5432 DB_NAME=cmp DB_USER=root DB_PASSWORD=root +# ========== Redis / KeyDB ========== # REDIS_HOST=redis REDIS_PORT=6379 REDIS_AUTH=redis_pass REDIS_DB_CACHE=0 REDIS_DB_SESSIONS=1 -SENTRY_DSN=https://hash@sentry.io/123 -API_DOCS_ENABLED=1 +# ========== Emails & SMTP server ========== # +MAILER_EMAIL=info@example.com +MAILER_FROM="Consent Management Platform" +# SMTP_ENABLED=1 +# SMTP_HOST=hostname +# SMTP_PORT=port +# SMTP_USERNAME=username +# SMTP_PASSWORD=password +# SMTP_SECURE=ssl # ssl or tls + +# ========== Google reCAPTCHA ========== # +RECAPTCHA_ENABLED=0 +# GOOGLE_RECAPTCHA_SITE_KEY=site-key +# GOOGLE_RECAPTCHA_SECRET_KEY=secret-key + +# ===== Sentry logger ===== # +#SENTRY_DSN=https://hash@sentry.io/123 diff --git a/.github/workflows/build.yml b/.github/workflows/build.yml index f8f14cfd..53363568 100644 --- a/.github/workflows/build.yml +++ b/.github/workflows/build.yml @@ -76,7 +76,7 @@ jobs: uses: docker/login-action@v2 if: ${{ github.event.inputs.push_to_hpt == 'true' }} with: - registry: registry.hptronic.cz + registry: gitlab2.hptronic.cz username: ${{ secrets.HPT_REGISTRY_USERNAME }} password: ${{ secrets.HPT_REGISTRY_TOKEN }} @@ -112,7 +112,7 @@ jobs: if: ${{ github.event.inputs.push_to_hpt == 'true' }} with: images: | - name=registry.hptronic.cz/dev/cmp/cmp + name=gitlab2.hptronic.cz/dev/cmp/cmp flavor: | latest=false tags: | @@ -125,7 +125,7 @@ jobs: if: ${{ github.event.inputs.push_to_hpt == 'true' }} with: images: | - name=registry.hptronic.cz/dev/cmp/cmp/worker + name=gitlab2.hptronic.cz/dev/cmp/cmp/worker flavor: | latest=false tags: | @@ -220,7 +220,7 @@ jobs: uses: docker/login-action@v2 if: ${{ github.event.inputs.push_to_hpt == 'true' }} with: - registry: registry.hptronic.cz + registry: gitlab2.hptronic.cz username: ${{ secrets.HPT_REGISTRY_USERNAME }} password: ${{ secrets.HPT_REGISTRY_TOKEN }} diff --git a/.gitignore b/.gitignore index 5740325a..7b4d17ff 100644 --- a/.gitignore +++ b/.gitignore @@ -1,22 +1,16 @@ # Application .env .env.local.php -vendor/ # Project files etc. -#nbproject .idea -#.settings -#.project -#.buildpath # Dev node_modules/ +vendor/ # Client-side public/dist/ # MacOS -#.DS_Store -#._.DS_Store -#._* +.DS_Store diff --git a/CHANGELOG.md b/CHANGELOG.md index 15ef876a..96632175 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -9,6 +9,11 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0 ### Added - Added optional ENV variables `REDIS_DB_CACHE` (default `0`) and `REDIS_DB_SESSIONS` (default `1`). +- Added the `Development Guide` and `Product Documentation`. + +### Changed + +- Updated the README. ## 0.12.0 - 2023-02-27 diff --git a/Makefile b/Makefile index f583b0b0..1072cee7 100644 --- a/Makefile +++ b/Makefile @@ -19,8 +19,9 @@ down: restart: make stop + make stop-worker make start - make data-migration + make start-worker cache: docker exec -it cmp-app bin/console @@ -95,6 +96,7 @@ init: make start make install make data + make start-worker data: make data-migration diff --git a/README.md b/README.md index d2d79bf9..ed1df0ee 100644 --- a/README.md +++ b/README.md @@ -1,6 +1,22 @@ -# Consent Management Platform - -> 🛡 Manage user consents and cookie widget with easy. +
+Consent Management Platform logo +

Consent Management Platform

+ +🛡 Easily manage user consents and the cookie widget. +
+ +
+ +- ✅ Managing cookies and providers in bulk +- ✅ Summary statistics on user consent positivity including their detailed histories +- ✅ Direct integration with [68publishers/cookie-consent](https://github.com/68publishers/cookie-consent) +- ✅ Configurable storages standardized by Google +- ✅ Automatic cookie detection using Crawler including proposals for changes +- ✅ Support for multiple environments (web, mobile app, etc.) +- ✅ Wide possibilities of integration with your projects +- ✅ Automated reporting +- ✅ Support of authentication with Azure AD +- And many more! ## Table of Contents * [About CMP](#about-cmp) @@ -9,10 +25,12 @@ * [Installation](#installation) * [Product Documentation](#product-documentation) * [Development Guide](#development-guide) -* [Known Issues](#known-issues) ## About CMP -... + +The CMP is a standalone application for storing user's cookie consents and managing the cookies themselves on any website or application. + +![CMP Application](docs/images/dashboard.png) ## Getting Started @@ -22,7 +40,7 @@ ### Installation ```sh -$ git clone cmp +$ git clone https://github.com/68publishers/consent-management-platform cmp $ cd cmp $ cp .env.dist .env $ make init @@ -30,22 +48,12 @@ $ make init Visit http://localhost:8888 and sign in via `admin@68publishers.io` / `admin` credentials. -See [Makefile](./Makefile) for other usefull commands. +See [Makefile](./Makefile) for other useful commands and the [Development Guide](docs/development.md) for information about ENV variables etc. ## Product Documentation -... -## Development Guide -... +For documentation of the application from a user perspective, please go to the [Product Documentation](docs/product.md). -## Known issues -When running application stack locally and get the following message: -```sh -An exception occurred in the driver: -SQLSTATE[08006] [7] could not translate host name "cmp-db" to address: Name does not resolve -``` +## Development Guide -Simply restart the `db` service manualy: -```sh -$ docker compose restart db -``` +For more technical information, please go to the [Development Guide](docs/development.md). diff --git a/config/packages/contributte.monolog.neon b/config/packages/contributte.monolog.neon index 09c4266b..eac765d7 100644 --- a/config/packages/contributte.monolog.neon +++ b/config/packages/contributte.monolog.neon @@ -6,7 +6,7 @@ services: autowired: no type: Sentry\Client factory: Sentry\ClientBuilder::create([ - dsn: ::env(SENTRY_DSN) + dsn: ::env(SENTRY_DSN, '') max_request_body_size: always ])::getClient() diff --git a/docs/development.md b/docs/development.md new file mode 100644 index 00000000..8f4fdfbe --- /dev/null +++ b/docs/development.md @@ -0,0 +1,248 @@ +
+Consent Management Platform logo +

Development Guide

+
+ +
+ +## Table of Contents +* [Stack](#stack) +* [ENV variables](#env-variables) +* [Frontend](#frontend) +* [Fixtures](#fixtures) +* [Sending emails](#sending-emails) +* [Console commands](#console-commands) +* [API and integration](#api-and-integration) +* [Cookies crawler](#cookies-crawler) +* [How to update to the latest version](#how-to-update-to-the-latest-version) +* [Production build](#production-build) +* [Contributing](#contributing) + +## Stack + +The application runs in Docker and consists of the following [services](../docker-compose.yml): + +- App (`cmp-app`) - Nginx webserver with PHP `8.1`, composer and yarn +- Worker (`cmp-worker`) - PHP `8.1` cli with supervisor +- Db (`cmp-db`) - PostgreSQL in the version `13.6` +- Redis (`cmp-redis`) - Redis in the version `7.0.10` + +You can connect to each of the containers using the following command. + +```sh +$ docker exec -it sh +``` + +## ENV Variables + +The application requires several ENV variables to be set. +The [.env.dist](../.env.dist) file contains ENVs for local development. Consider production configuration depending on your needs. + +| Variable name | Type | Required | Default | Additional info | +|-----------------------------|--------------------|----------|----------|-------------------------------------------------------------------------------------------------------------------------------------------| +| APP_DEBUG | Boolean | no | `1` | Forces debug mode. | +| APP_DEBUG_COOKIE_SECRET | String | no | - | The debug mode can be enabled with a cookie. A key is `debug_please` and a value is equal to the ENV variable. | +| PROJECT_URL | String | yes | - | Full URL to the document root of the application. | +| TRUSTED_PROXIES | CommaSeparatedList | no | - | The list of IP addresses (or ranges like 1.0.0.0/1) separated by a comma. Setup the variable if the site is running behind an HTTP proxy. | +| COOKIE_SECURE | Boolean | no | - | Send cookies only via HTTP or HTTPS. It is detected automatically from a request protocol if the variable is not set. | +| API_DOCS_ENABLED | Boolean | no | `0` | Enables OpenApi schema and Swagger UI endpoints. | +| GTM_CONTAINER_ID | String | no | `""` | Enables GTM. GTM will be initialized only if the variable exists and the value is not empty. | +| GRID_COUNT_LIMIT | Integer | no | `100000` | For performance reasons, the number of rows displayed in the administration data grids is limited. | +| DB_HOST | String | yes | - | - | +| DB_PORT | Integer | yes | - | - | +| DB_NAME | String | yes | - | - | +| DB_USER | String | yes | - | - | +| DB_PASSWORD | String | yes | - | - | +| REDIS_HOST | String | yes | - | - | +| REDIS_PORT | Integer | yes | - | - | +| REDIS_AUTH | String | no | - | Set only if Redis has a password. | +| REDIS_DB_CACHE | Integer | no | `0` | Redis database number for caching. | +| REDIS_DB_SESSIONS | Integer | no | `1` | Redis database number for sessions. | +| MAILER_EMAIL | String | yes | - | Email address for sending emails. | +| MAILER_FROM | String | no | - | Name of email address for sending emails. | +| SMTP_ENABLED | Boolean | no | `0` | Required in production environment only. Enables sending emails using SMTP. | +| SMTP_HOST | String | no | - | Required only if `SMTP_ENABLED=1`. | +| SMTP_PORT | Integer | no | - | Required only if `SMTP_ENABLED=1`. | +| SMTP_USERNAME | String | no | - | - | +| SMTP_PASSWORD | String | no | - | - | +| SMTP_SECURE | String | no | - | Required only if `SMTP_ENABLED=1`. Allowed values are `ssl` or `tls`. | +| RECAPTCHA_ENABLED | Boolean | no | `0` | Enables reCAPTCHA in the application (on the forgot password page). | +| GOOGLE_RECAPTCHA_SITE_KEY | String | no | - | The site key for Google reCAPTCHA v3 | +| GOOGLE_RECAPTCHA_SECRET_KEY | String | no | - | The secret key for Google reCAPTCHA v3 | +| SENTRY_DSN | String | no | - | DSN of the Sentry project for capturing application errors. | + +## Frontend + +As far as the visual side is concerned, the application is based mainly on Tailwind CSS and Alpine.js components. +The final build is created using Webpack Encore and PostCSS. + +You can rebuild the assets with following command: + +```sh +$ make install-assets +``` + +## Fixtures + +The default demo data is automatically imported when the application is [installed](../README.md#installation). +To reset the data, run the following command: + +```sh +$ make data +``` + +:exclamation: Do not run the fixtures on production! + +## Sending emails + +By default, emails are sent using the PHP function `mail()`. However, the `sendmail` extension is not installed in the container and therefore emails are not sent. +For this reason, you need to configure the SMPT server through the ENV variables. +For example, Google's SMTP server configuration would look something like this: + +```sh +SMTP_ENABLED=1 +SMTP_HOST=smtp.gmail.com +SMTP_PORT=465 +SMTP_USERNAME=your email address +SMTP_PASSWORD=your token +SMTP_SECURE=ssl +``` + +If the debug mode is enabled (`APP_DEBUG=1` or the user has set the `APP_DEBUG_COOKIE_SECRET` cookie in the browser), the emails are always saved to local files and can be viewed in the Tracy Bar. + +Emails in the Tracy Bar + +## Console commands + +The application contains several commands. Some of them should be set to CRONTAB for periodical execution. + +### Weekly overview + +The command sends a weekly report with project statistics to users who have this notification enabled. +Users will only receive statistics for the projects they have access to. + +```sh +$ bin/console cmp:weekly-overview +``` + +In CRONTAB, schedule the command to run once a week, e.g. every Monday at 4:00 a.m. + +### Consent decrease notification + +The command sends a notification of the previous day's consent decrease for all projects to users who have this notification enabled. +Users will only receive information for the projects they have access to. + +```sh +$ bin/console cmp:consent-decrease-notifier +``` + +In CRONTAB, schedule the command to run once a day, e.g. every day at 4:00 a.m. + +### Cookie suggestions notification + +If the application has configured a connection to the [crawler](#cookies-crawler), it is possible to send notifications about new cookie suggestions. + +The command sends a notification with new cookie suggestions to users who have this notification enabled. +Users will only receive suggestions for the projects they have access to. + +```sh +$ bin/console cmp:cookie-suggestions-notifier +``` + +In CRONTAB, schedule the command to as you see fit. For example, once a week. + +### Monthly statistics + +The command is designed to be run manually. The output is the number of consents per month in the selected year. +The command has the following options: + +- `--accepted-all` - Calculates number of users who have agreed to all categories of cookies. +- `--rejected-all` - Calculates the number of users who did not accept any cookie category. +- `--by-categories` - Calculates the number of users who have agreed to given categories. Use the category codes separated by a comma as the value. +- `--unique` - Count only unique (last) consents by user in a particular month. +- `--year` - Year for which statistics are to be calculated. Current year is used if the option is not provided. +- `--format` - Output format. Allowed values are `table` (default) and `csv`. + +Here are some examples: + +```sh +# Calculate number of users who have agreed to all categories of cookies: +$ bin/console cmp:monthly-statistics --accepted-all + +# Calculate the number of users who did not accept any cookie category: +$ bin/console cmp:monthly-statistics --rejected-all + +# Calculate the number of users who have agreed with categories `ad_storage` and `analytics_storage`: +$ bin/console cmp:monthly-statistics --by-categories "ad_storage,analytics_storage" + +# Calculate the number of users who have agreed with the category `ad_storage` but rejected the category `analytics_storage`: +$ bin/console cmp:monthly-statistics --by-categories "ad_storage,!analytics_storage" + +# The requested statistics can be returned in single runtime: +$ bin/console cmp:monthly-statistics --accepted-all --rejected-all --by-categories "ad_storage,analytics_storage" --by-categories "ad_storage,!analytics_storage" +``` + +## API and integration + +The application exposes the API to communicate with the cookie widget. + +All endpoints are described using OpenApi. To display the Swagger UI, set the ENV variable `API_DOCS_ENABLED` to `1` and open the page http://localhost:8888/api/docs in your browser. + +If your website using [68publishers/cookie-consent](https://github.com/68publishers/cookie-consent), there is no need to manually integrate or call anything. Everything is ready, and it is only necessary to configure the GTM tag correctly. +More information about the integration can be found in the [documentation](https://github.com/68publishers/cookie-consent#integration-with-cmp-application) of the `68publishers/cookie-consent` package. + +## Cookies crawler + +The application offers the possibility to connect with a cookie crawler. +If you wish to use the crawler in the CMP application, it is necessary to have a running instance of the [68publishers/crawler](https://github.com/68publishers/crawler) application. + +It should be noted that the crawler is relatively heavy on resources if it has to deal with difficult scenarios. + +The scenarios themselves are defined through the user interface of the CMP application, but defining them is rather a developer's job and requires knowledge of the mentioned crawler. + +## How to update to the latest version + +:exclamation: When updating, please always read the notes on newly released versions carefully! + +Usually there are several things to do, such as: + +- run composer install +- run yarn install +- run webpack encore +- run database migrations +- clear cache +- restart worker +- ... + +All of these tasks can be done after downloading the new version by running the following commands: + +```sh +$ make install +$ make restart +``` + +## Production build + +For production usage, there are prepared docker images on the [DockerHub](https://hub.docker.com/r/68publishers/cmp/tags). + +Two images are published with each new version of the application: + +- `68publishers/cmp:app-{version}` - the container with the application +- `68publishers/cmp:worker-{version}` - the container with the worker + +The images are already build, they contain all libraries, assets and so on. So there should be no need to manually install or build anything into them. + +## Contributing + +If you find any problems or have a specific question, please create an issue on GitHub. We will address it as soon as possible. +Please try to describe the issue as best you can (under what circumstances the issue arises, error messages, etc.). + +If you want to contribute to the code (ideally after the previous discussion in an issue), create a fork of the repository with its own branch and then create a pull request with it. + +Follow the uniform coding standards and coding style. + +Before committing and creating a pull request, run the following command: + +```sh +$ make cs +``` diff --git a/docs/images/categories-page.png b/docs/images/categories-page.png new file mode 100644 index 00000000..7ac7ca69 Binary files /dev/null and b/docs/images/categories-page.png differ diff --git a/docs/images/consents-page.png b/docs/images/consents-page.png new file mode 100644 index 00000000..84271925 Binary files /dev/null and b/docs/images/consents-page.png differ diff --git a/docs/images/cookie-management.png b/docs/images/cookie-management.png new file mode 100644 index 00000000..d920ab37 Binary files /dev/null and b/docs/images/cookie-management.png differ diff --git a/docs/images/cookie-widgets-page.png b/docs/images/cookie-widgets-page.png new file mode 100644 index 00000000..59ad09b6 Binary files /dev/null and b/docs/images/cookie-widgets-page.png differ diff --git a/docs/images/dashboard-page.png b/docs/images/dashboard-page.png new file mode 100644 index 00000000..f4f82c2f Binary files /dev/null and b/docs/images/dashboard-page.png differ diff --git a/docs/images/dashboard.png b/docs/images/dashboard.png new file mode 100644 index 00000000..a667badd Binary files /dev/null and b/docs/images/dashboard.png differ diff --git a/docs/images/edit-user-page.png b/docs/images/edit-user-page.png new file mode 100644 index 00000000..bc1cdcfd Binary files /dev/null and b/docs/images/edit-user-page.png differ diff --git a/docs/images/integration-page.png b/docs/images/integration-page.png new file mode 100644 index 00000000..be773e6f Binary files /dev/null and b/docs/images/integration-page.png differ diff --git a/docs/images/list-of-cookies-page.png b/docs/images/list-of-cookies-page.png new file mode 100644 index 00000000..69fa45bf Binary files /dev/null and b/docs/images/list-of-cookies-page.png differ diff --git a/docs/images/logo.svg b/docs/images/logo.svg new file mode 100644 index 00000000..7e8cc5a2 --- /dev/null +++ b/docs/images/logo.svg @@ -0,0 +1,3 @@ + + + diff --git a/docs/images/schedule-new-scenario.png b/docs/images/schedule-new-scenario.png new file mode 100644 index 00000000..d3addd20 Binary files /dev/null and b/docs/images/schedule-new-scenario.png differ diff --git a/docs/images/settings-authentication-with-azure-ad.png b/docs/images/settings-authentication-with-azure-ad.png new file mode 100644 index 00000000..842a2081 Binary files /dev/null and b/docs/images/settings-authentication-with-azure-ad.png differ diff --git a/docs/images/settings-crawler.png b/docs/images/settings-crawler.png new file mode 100644 index 00000000..dcbc7cb9 Binary files /dev/null and b/docs/images/settings-crawler.png differ diff --git a/docs/images/settings-environments.png b/docs/images/settings-environments.png new file mode 100644 index 00000000..38339fc2 Binary files /dev/null and b/docs/images/settings-environments.png differ diff --git a/docs/images/settings-localization.png b/docs/images/settings-localization.png new file mode 100644 index 00000000..a2f2b3c0 Binary files /dev/null and b/docs/images/settings-localization.png differ diff --git a/docs/images/settings-performance.png b/docs/images/settings-performance.png new file mode 100644 index 00000000..c24845db Binary files /dev/null and b/docs/images/settings-performance.png differ diff --git a/docs/images/tracy-bar-mails.png b/docs/images/tracy-bar-mails.png new file mode 100644 index 00000000..c0cea2ec Binary files /dev/null and b/docs/images/tracy-bar-mails.png differ diff --git a/docs/product.md b/docs/product.md new file mode 100644 index 00000000..638792ae --- /dev/null +++ b/docs/product.md @@ -0,0 +1,462 @@ +
+Consent Management Platform logo +

Product Documentation

+
+ +
+ +## Table of Contents +* [Dashboard](#dashboard) +* [Users](#users) +* [Settings](#settings) + * [Localization](#localization) + * [Environments](#environments) + * [Performance](#performance) + * [Crawler](#crawler) + * [Authentication with Azure AD](#authentication-with-azure-ad) +* [Cookies](#cookies) + * [Categories](#categories) + * [Providers](#providers) + * [List of cookies](#list-of-cookies) +* [Crawler](#crawler-1) + * [Scenario scheduling](#scenario-scheduling) + * [Running scenarios](#running-scenarios) +* [Imports](#imports) +* [Projects](#projects) + * [Consents](#consents) + * [Cookie widgets](#cookie-widgets) + * [Cookies > Providers](#cookies--providers) + * [Cookies > Project cookies](#cookies--project-cookies) + * [Cookies > Service cookies](#cookies--service-cookies) + * [Integration](#integration) + +## Dashboard + +The Dashboard contains statistics for all projects available to the logged user. +For each project, the following statistics are calculated for the selected period: + +| Type | Description | +|------------------|---------------------------------------------------------------------------------------------------------------------------------------------| +| Consents | The number of unique consents (regardless of the positivity of the consent). | +| Positivity | The percentage of unique consents that are positive (not counting necessary categories). | +| Consents (all) | Total number of consents. | +| Positivity (all) | The percentage positivity of all consents (not including necessary categories). | +| Providers | The number of cookie providers. | +| Cookies | The number of cookies. The first number are cookies bound to providers, the number in brackets are cookies defined directly on the project. | +| Last consent | Shows when the last consent was given (either positive or negative). | + +Dashboard page + +## Users + +Users are authenticated using an email and password, or by using [Azure Active Directory](#authentication-with-azure-ad). +Users cannot register themselves to the application, they must be added by an administrator. +The administrator can set a default password directly when creating a new user, or leave it blank and the user can choose own password using the "forgot password" functionality. +In addition, each user has assigned their projects that they can see and manage. + +The application provides only two roles - `admin` and `manager` with following privileges: + +| Resource/Action | Manager | Admin | +|-------------------------------------------------------------------|:------------------:|:------------------:| +| `Dashboard` | Manager | Admin | +| View statistics for projects that are visible to the current user | :white_check_mark: | :white_check_mark: | +| `User account` | Manager | Admin | +| Edit own data, change password | :white_check_mark: | :white_check_mark: | +| `Users > Users` | Manager | Admin | +| View the list of users | | :white_check_mark: | +| Create or edit a user | | :white_check_mark: | +| Delete a user | | :white_check_mark: | +| `Users > New password requests` | Manager | Admin | +| View the list of new password requests | | :white_check_mark: | +| `Settings` | Manager | Admin | +| View and edit the application settings | | :white_check_mark: | +| `Cookies > Categories` | Manager | Admin | +| View the list of categories | | :white_check_mark: | +| Create or edit a category | | :white_check_mark: | +| Delete a category | | :white_check_mark: | +| `Cookies > Providers` | Manager | Admin | +| View the list of providers | | :white_check_mark: | +| Create or edit a provider | | :white_check_mark: | +| Delete a provider | | :white_check_mark: | +| `Cookies > List of cookies` | Manager | Admin | +| View the list of cookies | | :white_check_mark: | +| Create or edit a cookie | | :white_check_mark: | +| Delete a cookie | | :white_check_mark: | +| `Cookies > Cookie suggestions` | Manager | Admin | +| View the list of projects | | :white_check_mark: | +| View the list of cookie suggestions per project | | :white_check_mark: | +| Resolve cookie suggestions | | :white_check_mark: | +| `Crawler > Scenario scheduling` | Manager | Admin | +| View the list of scenarios | | :white_check_mark: | +| Create or edit a scenario | | :white_check_mark: | +| `Crawler > Running scenarios` | Manager | Admin | +| View the list and details of scenarios | | :white_check_mark: | +| `Imports` | Manager | Admin | +| View the list of executed imports | | :white_check_mark: | +| Run an import | | :white_check_mark: | +| `Projects` | Manager | Admin | +| View the list of projects that are visible by the current user | :white_check_mark: | :white_check_mark: | +| Create a project | | :white_check_mark: | +| `Project > Consents` | Manager | Admin | +| View the list of consents | :white_check_mark: | :white_check_mark: | +| `Project > Cookie widgets` | Manager | Admin | +| View the list of cookie widgets | :white_check_mark: | :white_check_mark: | +| `Project > Cookies > Providers` | Manager | Admin | +| View and edit project providers | :white_check_mark: | :white_check_mark: | +| `Project > Cookies > Project cookies` | Manager | Admin | +| View the list of project cookies | :white_check_mark: | :white_check_mark: | +| Create or edit a project cookie | :white_check_mark: | :white_check_mark: | +| Delete a project cookie | :white_check_mark: | :white_check_mark: | +| `Project > Cookies > Service cookies` | Manager | Admin | +| View the list of service cookies | :white_check_mark: | :white_check_mark: | +| `Project > Integration` | Manager | Admin | +| View and edit cookie table templates | | :white_check_mark: | +| View a cookie table integration code | :white_check_mark: | :white_check_mark: | +| `Project > Edit project` | Manager | Admin | +| View and edit a project | | :white_check_mark: | +| Delete a project | | :white_check_mark: | + +Edit user page + +## Settings + +### Localization + +This section is used to set the languages that are used on the websites that are connected to the CMP. + +The "Translation locales" field should contain a complete list of all languages. +The default language is used if any record lacks a translation for the requested language. + +Setting page + +### Environments + +The cookies widget can send consents in different environments if it is configured in this way. In order to separate these environments in the list of consents, statistics and other places, it is necessary to define all the environments that are used. + +If the widget has no configured environments, just leave the `default` environment. + +Setting page + +### Performance + +When loading cookie lists (cookie tables) into the cookie widget, it is possible to optimize requesting the CMP API using this configuration. + +For production use, it is recommended to enable the "HTTP Header ETag" and "HTTP Header Cache-Control" options and set the "HTTP Header Cache-Control: max-age" field to some meaningful value, such as `3600` (1 hour). + +Setting page + +### Crawler + +The application can be connected to the crawler API, which can be used to crawl the project's website and search for cookies. +For this purpose, there are scenarios that can be defined after successful connection of the crawler. + +Found cookies are then sent to the CMP, where an evaluation is performed to see if these cookies exist in the CMP, if they are problematic (for example, they are used on the page even though the user did not agree to them), etc. + +Setting page + +### Authentication with Azure AD + +Users can be authenticated to the CMP application using Azure Active Directory. + +To do this, it is required to create an enterprise application in Azure and create a secret code for it. The application ID and the secret code (and possibly the tenant ID) must be set in the CMP configuration afterward. +The value of the "Callback URI" field, on the other hand, must be set as the "Redirect URI" in the Azure enterprise application. +Next, the `admin` and `manager` roles need to be created in Azure for the enterprise application. + +Setting page + +## Cookies + +Cookie management is based on the fact that cookie categories and cookie providers are defined. +Each provider is assigned its own cookies and the providers are then assigned to individual projects. + +Cookie management diagram + +### Categories + +The same categories of cookies (storages) that are used on the project's website should be defined in the application. At least the codes should be the same. + +Be sure to mark the necessary category with the "Necessary category" flag. + +The default installation will automatically create categories that are [defined by Google](https://policies.google.com/technologies/cookies?hl=en-US#types-of-cookies). + +Categories page + +### Providers + +A provider could be defined as a group of cookies. + +For example, if the project website uses Google Analytics, there would be a provider in the CMP called "Google Analytics" that would have cookies related to that service. + +### List of cookies + +Although cookies are managed through individual providers, the list of all cookies can be found on this page. + +Categories page + +### Cookie suggestions + +This menu item will appear if the crawler is integrated into the application via [settings](#crawler). +There is the list of projects for which some crawler scenario has already been successfully run. +Each project also has its own detail, on which the cookie suggestions are located. + +The suggestions are divided into several types: + +- **New cookies** + - Cookies that were found on the website but do not exist in the CMP + - Cookies that were found on the website, exist in the CMP, but are not assigned to the current project. +- **Problematic cookies** + - Cookies that were never found + - Cookies that have not been found for a long time (more than 14 days). + - Cookies that have been found on the website, but their category has not been agreed. +- **Unproblematic cookies** - Cookies for which no problem has been found. +- **Ignored cookies** - Cookie suggestions that have been temporarily or permanently marked as ignored. + +## Crawler + +This menu item will appear if the crawler is integrated into the application via [settings](#crawler). +The crawler is an external application that runs standalone. For more information follow the [Development Guide](./development.md#cookies-crawler). + +### Scenario scheduling + +To ensure that the crawler knows what pages to look for and how to behave on them, it needs to be provided with scenarios. +In addition, each scenario must be configured when to run (crontab syntax) and which cookie categories are allowed in the scenario. Problematic cookies are then evaluated according to these categories. + +
+ Example scenario from the picture + +```json +{ + "options": { + "session": { + "transferredCookies": [ + "cc-settings" + ] + }, + "viewport": { + "width": 800, + "height": 600 + }, + "maxRequests": 100, + "maxConcurrency": 6, + "maxRequestRetries": 2 + }, + "scenes": { + "startup": [ + { + "action": "runScene", + "options": { + "scene": "acceptCookies" + } + }, + { + "action": "collectCookies", + "options": {} + }, + { + "action": "enqueueLinks", + "options": { + "scene": "navigation", + "baseUrl": "{{location.origin}}", + "selector": "#navigation", + "strategy": "same-domain" + } + } + ], + "navigation": [ + { + "action": "collectCookies", + "options": {} + }, + { + "action": "enqueueLinks", + "options": { + "scene": "navigation", + "selector": "#main", + "strategy": "same-domain" + } + } + ], + "acceptCookies": [ + { + "action": "click", + "options": { + "selector": "#c-p-bn" + } + }, + { + "action": "delay", + "options": { + "delay": 2000 + } + } + ] + }, + "entrypoint": { + "url": "https://www.example.com", + "scene": "startup" + } +} +``` + +The scenario setting says that we always transfer the `cc-settings` cookie between requests, regardless of the browser session. +It also specifies that a maximum of 100 pages will be crawled, at most 6 at a time, and if a page responds with an error code, the crawler will try to call the page twice more. The window size is set to `800x600` pixels. + +The scenario then does the following: + +- Opens the page https://www.example.com. +- Clicks on the button with ID `#c-p-bn` (Button to accept all cookies). +- Collects information about all cookies from the page. +- Finds links in the element `#navigation` and executes the scene `navigation` with them. + - On each of these pages, cookies information is collected. + - On each of these pages, it finds links in the element `#main` and starts the scene `navigation` with them again (recursion). + +
+
+ +Categories page + +### Running scenarios + +Here is the list of scenarios that are currently running or are already finished. By clicking on the detail it will display all the information about the scenario, what cookies it found, which pages it visited or screenshots it took. + +There is also an option to manually run any scenario once. + +## Imports + +Providers and cookies can be managed externally in `CSV` or `JSON` format or, for example, in an application such as Microsoft Excel or Google Sheets. +Data in these formats can be imported into the application. + +Here are examples of how the imported files should look like: + +
+ Cookie providers import in CSV format + +```csv +code|name|type|link|active|projects|purpose.cs|purpose.en +facebook_login|Facebook Login|3rd_party|https://www.facebook.com/about/privacy/|1|demo,test|"Platforma pro přihlášení skrze Facebook."|"Facebook login platform." +# ... more rows ... +``` + +
+ +
+ Cookie providers import in JSON format + +```json5 +[ + { + "code": "facebook_login", + "name": "Facebook login", + "type": "3rd_party", + "link": "https://www.facebook.com/about/privacy/", + "active": true, + "projects": [ + "demo", + "test" + ], + "purpose": { + "cs": "Platforma pro přihlášení skrze Facebook.", + "en": "Facebook login platform." + } + } + // ... more providers ... +] +``` + +
+ +- Allowed values for the field `type` are `1st_party` and `3rd_party` +- Projects in CSV must be comma separated list +- In CSV, each locale for `purpose` field must be separated column in the format `purpose.` + +
+ Cookies import in CSV format + +```csv +name|domain|category|provider|processingTime|active|purpose.cs|purpose.en|environments +c_user|example.com|security_storage|facebook_login|session|1|"Facebook ID zákazníka."|"Customer\'s Facebook ID."|"mobile" +# ... more rows ... +``` + +
+ +
+ Cookies import in JSON format + +```json5 +[ + { + "name": "c_user", + "domain": "example.com", + "category": "security_storage", + "provider": "facebook_login", + "processingTime": "session", + "active": true, + "purpose": { + "cs": "Facebook ID zákazníka.", + "en": "Customer\'s Facebook ID." + }, + "environments": [ + "mobile" + ] + } + // ... more cookies ... +] +``` + +
+ +- The field `domain` can be an empty string. In this case the project domain will be used when cookies are returned via CMP API. +- The field `category` must contain a category code +- The field `provider` must contain a provider code +- Allowed values for the field `processingTime` are `"session"`, `"persistent"` or a duration string +- The field `environments` must contain a list of environment codes. The code for the default environment is always `"default"`. +- In JSON, use en empty array for the field `environments` if the cookie are for all environments +- In CSV, use an empty value for the field `environments` if the cookie are for all environments. If the cookie is in multiple environments, use a comma separated list e.g. `default,mobile`. +- In CSV, each locale for `purpose` field must be separated column in the format `purpose.` + +For importing the main (1st party) provider, it is necessary that its project already exists. If the project doesn't exist, the provider will be created as a generic provider that can be assigned to any project. + +So the correct procedure is to create projects first and then import the data. + +## Projects + +After selecting a specific project, the user is moved to the context of the selected project where he can see consents, cookie widget settings and manage project cookies. + +### Consents + +There is the list of all recorded consents. +The consents are grouped according to the user identifier that the cookie widget creates and sends. After clicking on the detail, the complete consent history of the user is displayed. + +Consents page + +### Cookie widgets + +On this page are listed the settings of all cookie widgets used on the project website. +The uniqueness of the cookie widget is determined by the checksum that is calculated and sent by the cookie widget itself. + +Cookie widgets page + +### Cookies > Providers + +This page allows to set the basic information about the main (1st party) provider and also to assign other providers respectively individual service providers to the project. + +### Cookies > Project cookies + +The main (1st party) provider cookies can be managed on this page. These cookies are related only to the current project. + +### Cookies > Service cookies + +On this page is the list of all cookies of providers that are associated with the current project. The list is readonly. + +### Integration + +By integration is meant the ability to easily render a table with providers, alternatively with cookies, directly on the project website. For example, through a static page. + +A template that fits exactly into the design of the website can be defined for each locale. The table can be displayed by copying the generated script to the website. + +The templates are written in the [Latte](https://latte.nette.org/) templating language and two variables can be accessed - `$providers` and `$cookies`. It is recommended leaving the creation of the templates to the developer. + +Values of the provided variables exactly copy the response from the endpoint `/api/v{version}/cookies/{project}`. More information about the API in the [Development Guide](development.md). + +Integration page diff --git a/environments b/environments deleted file mode 100644 index cb97c35d..00000000 --- a/environments +++ /dev/null @@ -1,10 +0,0 @@ -- GlobalSettings - OK -- Project form - OK -- Consents list - OK -- History - OK -- Consents API - OK -- Cookies list API - OK (check filtering) -- Cookies form - OK -- Cookies API - OK -- Integration - OK -- Dashboard - OK