diff --git a/.env.dist b/.env.dist index d5f07d22..5dbe5cc0 100644 --- a/.env.dist +++ b/.env.dist @@ -6,12 +6,7 @@ # 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@example.com -# MAILER_EMAIL=info@example.com -# MAILER_FROM=info # RECAPTCHA_ENABLED=1 # GOOGLE_RECAPTCHA_SITE_KEY=site-key @@ -43,14 +38,10 @@ ######################################################################################################################## APP_DEBUG=1 -APP_DEBUG_COOKIE_SECRET=idontgiveabuck07 +APP_DEBUG_COOKIE_SECRET=hey_tracy COOKIE_SECURE=0 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 @@ -64,8 +55,8 @@ REDIS_HOST=redis REDIS_PORT=6379 REDIS_AUTH=redis_pass -MAILER_EMAIL=info@example.com -MAILER_FROM=CMP +MAILER_EMAIL=info@cmp.io +MAILER_FROM="Consent Management Platform" SENTRY_DSN=https://hash@sentry.io/123 API_DOCS_ENABLED=1 diff --git a/LICENSE.md b/LICENSE.md new file mode 100644 index 00000000..d662eaa7 --- /dev/null +++ b/LICENSE.md @@ -0,0 +1,21 @@ +# MIT License + +Copyright (c) 2022 '68 Publishers + +> Permission is hereby granted, free of charge, to any person obtaining a copy +> of this software and associated documentation files (the "Software"), to deal +> in the Software without restriction, including without limitation the rights +> to use, copy, modify, merge, publish, distribute, sublicense, and/or sell +> copies of the Software, and to permit persons to whom the Software is +> furnished to do so, subject to the following conditions: +> +> The above copyright notice and this permission notice shall be included in all +> copies or substantial portions of the Software. +> +> THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR +> IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, +> FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE +> AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER +> LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, +> OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE +> SOFTWARE. diff --git a/README.md b/README.md index d2d79bf9..5052b663 100644 --- a/README.md +++ b/README.md @@ -1,6 +1,11 @@ -# Consent Management Platform +
+Consent Management Platform logo +

Consent Management Platform

-> 🛡 Manage user consents and cookie widget with easy. +🛡 Easily manage user consents and the cookie widget. +
+ +
## Table of Contents * [About CMP](#about-cmp) @@ -9,20 +14,24 @@ * [Installation](#installation) * [Product Documentation](#product-documentation) * [Development Guide](#development-guide) -* [Known Issues](#known-issues) +* [License](#license) ## About CMP -... + +The CMP is a standalone application for logging cookie consent and managing the cookies themselves on any website. +You can implement the integration with the application in the cookie bar on your website, however, if you use [our solution](https://github.com/68publishers/cookie-consent), the integration is ready for you. + +![CMP Application](docs/images/dashboard.png) ## Getting Started ### Prerequisites -- Docker +- Docker Compose - Make ### 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 +39,16 @@ $ 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 -... + +For documentation of the application from a user perspective, please go to the [Product Documentation](docs/product.md). ## Development Guide -... -## 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 -``` +For more technical information, please go to the [Development Guide](docs/development.md). -Simply restart the `db` service manualy: -```sh -$ docker compose restart db -``` +## License + +The package is distributed under the MIT License. See [LICENSE](LICENSE.md) for more information. diff --git a/docs/development.md b/docs/development.md new file mode 100644 index 00000000..ccf96e94 --- /dev/null +++ b/docs/development.md @@ -0,0 +1,172 @@ +
+Consent Management Platform logo +

Development Guide

+
+ +
+ +## Table of Contents +* [Stack](#stack) +* [ENV variables](#env-variables) +* [Frontend](#frontend) +* [Fixtures](#fixtures) +* [Sending emails](#sending-emails) +* [API and integration](#api-and-integration) +* [How to update to the latest version](#how-to-update-to-the-latest-version) +* [Contributing](#contributing) + +## Stack + +The application runs in Docker and consists of [three services](../docker-compose.yml): + +1) App - Nginx webserver with PHP `7.4`, composer and yarn +2) Db - PostgreSQL in the version `13.6` +3) Redis - Redis in the version `5.0.8` + +The container names are `cmp-app`, `cmp-db` and `cmp-redis`. +You can connect to each of the containers using the following command + +```sh +$ docker exec -it sh +``` + +The migration to PHP 8.x is of course planned soon, but for the time being we had to stick with version 7.4 for internal reasons. + +## ENV Variables + +The application needs several correctly set ENV variables to run correctly. +In the default installation, the variables are set for the application to work, but for production use, some of them need to be set/re-set + +| Variable name | Type | Default | Additional info | +|-----------------------------|--------------------|-----------------------------|------------------------------------------------------------------------------------------------------------------| +| APP_DEBUG | Boolean | 1 | Forces dev/debug mode | +| APP_DEBUG_COOKIE_SECRET | String | hey_tracy | The dev/debug mode can be enabled with cookie. A key is `debug_please` and a value is equal to this ENV variable | +| COOKIE_SECURE | Boolean | 0 | True for sending a secure flag (https) | +| PROJECT_URL | String | http://localhost:8888 | Full URL to the document root of the application | +| TRUSTED_PROXIES | CommaSeparatedList | - | Optional, IP or IPs separated by a comma. The range you can enter like 1.0.0.0/1 | +| RECAPTCHA_ENABLED | Boolean | 0 | Enables/Disables recaptcha in the application (forgot password) | +| GOOGLE_RECAPTCHA_SITE_KEY | String | - | The site key for Google Recaptcha v3 | +| GOOGLE_RECAPTCHA_SECRET_KEY | String | - | The secret key for Google Recaptcha | +| DB_HOST | String | 127.0.0.1 | - | +| DB_PORT | Int | 5432 | - | +| DB_NAME | String | cmp | - | +| DB_USER | String | root | - | +| DB_PASSWORD | String | root | - | +| REDIS_HOST | String | 127.0. 0.1 | - | +| REDIS_PORT | Int | 6379 | - | +| REDIS_AUTH | String | redis_pass | Password, optional | +| SMTP_ENABLED | Boolean | 0 | - | +| SMTP_HOST | String | - | - | +| SMTP_PORT | Int | - | - | +| SMTP_USERNAME | String | - | - | +| SMTP_PASSWORD | String | - | - | +| SMTP_SECURE | String | - | `ssl` or `tls` | +| MAILER_EMAIL | String | info@cmp.io | Email address for email sending | +| MAILER_FROM | String | Consent Management Platform | Name for email address for email sending | +| SENTRY_DSN | String | https://hash@sentry.io/123 | - | +| GTM_CONTAINER_ID | String | - | Optional, GTM will be initialized only if the variable is passed. | +| API_DOCS_ENABLED | Boolean | 1 | Optional, enables OpenApi schema and Swagger UI. | + +All ENV variables are also listed in the [.env.dist](../.env.dist) file. + +## 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 +``` + +The command internally runs `yarn install` and webpack encore in the production mode. + +Alternatively, the build can be run manually directly inside the container: + +```sh +$ docker exec -it cmp-app sh +$ yarn run encore prod # or `dev` +``` + +## Fixtures + +Default demo data is automatically imported when the application is [installed](../README.md#installation). +If you want to restart the data, you can do id by running the following command: + +```sh +$ make data +``` + +Alternatively: + +```sh +$ docker exec -it cmp-app sh +$ bin/console doctrine:fixtures:load +``` + +:exclamation: Do not run 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 + +## API and integration + +The application exposes out API to communicate with the cookie bar. + +All endpoints are described using OpenApi. To display the Swagger UI, set the ENV variable `API_DOCS_ENABLED` to `1` and open the `http://localhost:8888/api/docs` page in your browser. + +If you use [68publishers/cookie-consent](https://github.com/68publishers/cookie-consent) on your sites, there is no need to manually integrate or call anything, everything is already prepared, and you just need to set the GTM tag correctly. +You can read how to integrate it in the 68publishers/cookie-consent documentation. + +@TODO documentation link + +## 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 +- ... + +All these tasks are included in the `make install` command, so in most cases it should be enough to download the latest version of the application and run: + +```sh +$ make install +``` + +## 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 in the application container: + +```sh +$ vendor/bin/php-cs-fixer fix -v +``` diff --git a/docs/images/categories-page.png b/docs/images/categories-page.png new file mode 100644 index 00000000..727bc7a0 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..a5d363a8 Binary files /dev/null and b/docs/images/consents-page.png differ diff --git a/docs/images/cookie-bar-page.png b/docs/images/cookie-bar-page.png new file mode 100644 index 00000000..c4f053ac Binary files /dev/null and b/docs/images/cookie-bar-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/dashboard-page.png b/docs/images/dashboard-page.png new file mode 100644 index 00000000..339be03a Binary files /dev/null and b/docs/images/dashboard-page.png differ diff --git a/docs/images/dashboard-stats.png b/docs/images/dashboard-stats.png new file mode 100644 index 00000000..5be7b919 Binary files /dev/null and b/docs/images/dashboard-stats.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..0b8f81dd 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..8f7651ba 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..b1ce67e4 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/settings-page.png b/docs/images/settings-page.png new file mode 100644 index 00000000..d94c5fe8 Binary files /dev/null and b/docs/images/settings-page.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..ca349803 --- /dev/null +++ b/docs/product.md @@ -0,0 +1,263 @@ +
+Consent Management Platform logo +

Product Documentation

+
+ +
+ +## Table of Contents +* [Dashboard](#dashboard) +* [Users](#users) +* [Settings](#settings) +* [Cookies](#cookies) + * [Categories](#categories) + * [Providers](#providers) + * [List of cookies](#list-of-cookies) +* [Imports](#imports) +* [Projects](#projects) + * [Consents](#consents) + * [Cookies bars](#cookie-bars) + * [Project cookies](#project-cookies) + * [Integration](#integration) + +## Dashboard + +The Dashboard contains statistics for all projects available to the logged-in user. +For each project, 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 of the project, 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 log in with their email and password. 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/Active | Manager | Admin | +|-------------------------------------------------------------------|:------------------:|:------------------:| +| `Dashboard` | Manager | Admin | +| View statistics for projects that are visible by 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: | +| `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 bars` | Manager | Admin | +| View the list of cookie bars | :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 > 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 + +The application settings page now contains only the localization for entries. In the "Translation locales" field, select the locales you use on your site. +Cookies descriptions etc. will then be administered for the selected locales. + +The default locale will be used if any record is missing a given translation. + +Setting page + +## Cookies + +Cookie management is based on the fact that we have defined categories and cookie providers. +Each provider is assigned its own cookies and the providers are then assigned to individual projects. + +Cookie management diagram + +### Categories + +Categories should be defined in the same way as you use them on your site. At least the same codes. +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), but there is nothing stopping you from customizing them for your use. + +Categories page + + +### Providers + +We could define providers as groups of cookies. + +For example, we have Google Analytics deployed on our website. In this case, we will have a "Google Analytics" provider and this will contain cookies that are related to the service. + +On a provider's edit page, we can manage also their cookies. + +### List of cookies + +Although cookies are managed through individual providers, we have listed all cookies here for clarity. + +Categories page + +## 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. +Then you only need to run an import and the data will be transferred to 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|category|provider|processingTime|active|purpose.cs|purpose.en +c_user|security_storage|facebook_login|session|1|"Facebook ID zákazníka."|"Customer\'s Facebook ID." +# ... more rows ... +``` + +
+ +
+ Cookies import in JSON format + +```json5 +[ + { + "name": "c_user", + "category": "security_storage", + "provider": "facebook_login", + "processingTime": "session", + "active": true, + "purpose": { + "cs": "Facebook ID zákazníka.", + "en": "Customer\'s Facebook ID." + } + } + // ... more cookies ... +] +``` + +
+ +- 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 +- In CSV, each locale for `purpose` field must be separated column in the format `purpose.` + +If you want to import the main (1st party) provider, make sure that the project is already established. 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 establish your 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 bar settings and manage project cookies. + +### Consents + +Here is the list of all recorded consents. +The consents are grouped according to the user identifier that the cookie bar creates and sends. After clicking on a detail, you can see the complete history of that user. + +Consents page + +### Cookie bars + +On this page you can find the settings of all cookie bars used. +The uniqueness of the cookie bar is determined by the checksum that is calculated and sent by the cookie bar itself. + +Cookie bars page + +### Project cookies + +Here you can manage the main (1st party) provider that is only bound to the project whose context you are currently in. +Also, cookies that are only associated with the project are managed here. + +### Integration + +By integration, we mean the ability to easily render a table with providers, alternatively with cookies, directly on your website. For example, through a static page. + +You can define a template that fits exactly into the design of your website and then render it by copying and pasting it into one of your pages. + +We recommend leaving the creation of the template to the programmer, the template is written in the [Latte](https://latte.nette.org/) templating language and has two variables - `$providers` and `$cookies`. + +Their values exactly copy the response from the endpoint `/api/{version}/cookies/{project}`. You can learn more about the API in the [Development Guide](development.md). + +Integration page diff --git a/src/.DS_Store b/src/.DS_Store new file mode 100644 index 00000000..2a0e7a43 Binary files /dev/null and b/src/.DS_Store differ diff --git a/src/Application/Fixture/resources/demo.php b/src/Application/Fixture/resources/demo.php index e8c24a82..02245e7c 100644 --- a/src/Application/Fixture/resources/demo.php +++ b/src/Application/Fixture/resources/demo.php @@ -185,7 +185,7 @@ 'project_ids' => [ $fixtures['project']['demo']['project_id'], ], - 'profile' => 'cs', + 'profile' => 'en', 'timezone' => 'Europe/Prague', ], 'manager' => [ @@ -199,7 +199,7 @@ 'project_ids' => [ $fixtures['project']['demo']['project_id'], ], - 'profile' => 'cs', + 'profile' => 'en', 'timezone' => 'Europe/Prague', ], ]; diff --git a/translations/layout.en.neon b/translations/layout.en.neon index eff106e5..16ed1b3c 100644 --- a/translations/layout.en.neon +++ b/translations/layout.en.neon @@ -22,7 +22,7 @@ sidebar_project: cookies_providers: Providers cookies_cookies: Project cookies integration: Integration - edit_project: Edit projekt + edit_project: Edit project profile: settings: User account