Skip to content

Commit

Permalink
Merge pull request #122 from humanmade/1280-documentation-linting-issues
Browse files Browse the repository at this point in the history 
Reformat docs files after linting
  • Loading branch information
@mikelittle
mikelittle authored Jul 15, 2024
2 parents 2a6d6b5 + 848c0c5 commit 44d01d2
Show file tree
Hide file tree
Showing 11 changed files with 459 additions and 280 deletions.
2 changes: 1 addition & 1 deletion .travis.yml
View file
Original file line number Diff line number Diff line change
@@ -1,7 +1,7 @@
# Import Travis configuration from dev-tools repo
version: ~> 1.0
import:
- source: humanmade/altis-dev-tools:travis/module.yml@4accc74
- source: humanmade/altis-dev-tools:travis/module.yml@0bfa112a
mode: deep_merge_append

# Add your custom config below, which will merge with the default module config from the section above.
12 changes: 8 additions & 4 deletions docs/README.md
View file
Original file line number Diff line number Diff line change
@@ -1,9 +1,13 @@
# Privacy

Altis is committed to prividing frameworks, tooling and, where possible, integrations with other modules and platforms to enable customers to build privacy-first solutions.
Altis is committed to providing frameworks, tooling and, where possible, integrations with other modules and platforms to enable
customers to build privacy-first solutions.

Privacy is a core capabiliity for the modern web and something every customer and project has to deal with. Right now, a diverse array of solutions are available for web applications, and each requires custom integration work to get the most out of them.
Privacy is a core capability for the modern web and something every customer and project has to deal with. Right now, a diverse
array of solutions are available for web applications, and each requires custom integration work to get the most out of them.

Altis provides a consistent method for dealing with acquiring consent, managing user data and documenting privacy measures. In addition, we integrate and provide the controls for managing privacy in Altis' built-in features including analytics, personalization and Google Tag Manager.
Altis provides a consistent method for dealing with acquiring consent, managing user data and documenting privacy measures. In
addition, we integrate and provide the controls for managing privacy in Altis' built-in features including analytics,
personalization and Google Tag Manager.

Privacy is provided within Altis as a first-class component.
Privacy is provided within Altis as a first-class component.
82 changes: 58 additions & 24 deletions docs/consent/README.md
View file
Original file line number Diff line number Diff line change
@@ -1,55 +1,89 @@
# Altis Consent

The Altis Consent API provides a website administrator (you) with a centralized and consistent way of obtaining data privacy consent from your website's visitors. Data privacy consent refers to how user data is tracked, collected, or stored on a website.
The Altis Consent API provides a website administrator (you) with a centralized and consistent way of obtaining data privacy consent
from your website's visitors. Data privacy consent refers to how user data is tracked, collected, or stored on a website.

### Web Cookies
A website uses cookies to track user behaviour on the website. Cookies can be thought of as belonging to one of two broad types: first-party cookies, set by the server or code on the domain itself, and third-party cookies served by scripts included from other domains or services (such as Google Analytics). Depending on their function, these cookies can further be categorized into functional or operational cookies, marketing or personalization cookies, or cookies used for statistical data. While functional cookies are necessary for a smooth user experience, other cookies, such as marketing cookies that track user preferences, are not essential for a website's performance. General Data Protection Regulation (GDPR) governs user data privacy and protection and stipulates that businesses require appropriate consent from website visitors before they are served any such cookies.
## Web Cookies

We created this framework to help you readily obtain consent from your website users for various cookies that will be served on your website. With the features available in the API, a website's visitor will be able to control the _types_ of data or cookies that can be stored and shared if you choose to offer that level of control.
A website uses cookies to track user behaviour on the website. Cookies can be thought of as belonging to one of two broad types:
first-party cookies, set by the server or code on the domain itself, and third-party cookies served by scripts included from other
domains or services (such as Google Analytics). Depending on their function, these cookies can further be categorized into
functional or operational cookies, marketing or personalization cookies, or cookies used for statistical data. While functional
cookies are necessary for a smooth user experience, other cookies, such as marketing cookies that track user preferences, are not
essential for a website's performance. General Data Protection Regulation (GDPR) governs user data privacy and protection and
stipulates that businesses require appropriate consent from website visitors before they are served any such cookies.

We created this framework to help you readily obtain consent from your website users for various cookies that will be served on your
website. With the features available in the API, a website's visitor will be able to control the _types_ of data or cookies that can
be stored and shared if you choose to offer that level of control.

## Why should I use it?
To keep up with the GDPR regulations and your company's privacy and cookie policies. GDPR regulations mandate that businesses need user consent before they can collect or track any visitor data. This tool helps you create a cookie consent banner out of the box. With the banner options, a user can choose to select the cookies (data) that can be collected by the website. The framework lets you manage first party and third party cookies.

To keep up with the GDPR regulations and your company's privacy and cookie policies. GDPR regulations mandate that businesses need
user consent before they can collect or track any visitor data. This tool helps you create a cookie consent banner out of the box.
With the banner options, a user can choose to select the cookies (data) that can be collected by the website. The framework lets you
manage first party and third party cookies.

## How does it work?

Altis Consent is an API that is designed to help you manage when to load scripts that set cookies and other types of data stored locally on a user's computer. It allows you to subscribe to changes in a user's consent and use those events to trigger Google Tag Manager tags, or to lazily load other JavaScript that sets cookies.
Altis Consent is an API that is designed to help you manage when to load scripts that set cookies and other types of data stored
locally on a user's computer. It allows you to subscribe to changes in a user's consent and use those events to trigger Google Tag
Manager tags, or to lazily load other JavaScript that sets cookies.

## What does it do?

Out of the box, the Consent API supports [Altis Analytics](docs://analytics/native/README.md) and [Google Tag Manager](docs://analytics/google-tag-manager/README.md). Using the controls provided on the Privacy page in the WP admin you can link your website's Privacy Policy and Cookie storage Policy page.
Out of the box, the Consent API supports [Altis Analytics](docs://analytics/native/README.md)
and [Google Tag Manager](docs://analytics/google-tag-manager/README.md). Using the controls provided on the Privacy page in the WP
admin you can link your website's Privacy Policy and Cookie storage Policy page.

There are options to control whether to grant the user a choice to select the types of cookies they want to consent to, or an option to allow all cookies or only functional cookies. You may also easily add a cookie consent banner message in the admin settings.
There are options to control whether to grant the user a choice to select the types of cookies they want to consent to, or an option
to allow all cookies or only functional cookies. You may also easily add a cookie consent banner message in the admin settings.

In addition, a robust templating system and dozens of filters allow development teams to fully customize the options or the display of the banner, or only customize certain specific elements, based on a site's needs.
In addition, a robust templating system and dozens of filters allow development teams to fully customize the options or the display
of the banner, or only customize certain specific elements, based on a site's needs.

## What about third-party cookies?
The API allows management of third party cookies if it is configured so. See the [JavaScript Reference](./javascript-reference.md) to see how this can be done.

The API allows management of third party cookies if it is configured so. See the [JavaScript Reference](./javascript-reference.md)
to see how this can be done.

## Can I manage user data tracked through Altis' personalization features?

Altis' personalization features track user data using first-party cookies and are supported by default.

## Does the API help categorize the type of cookies?
Altis does not do any automatic categorisation of your cookies. It provides the means for users to control their consent and for you to respond to changes in that consent. Determining which scripts fall into which category needs to be manually determined and can vary by geographical location.

Out of the box, [five categories](./consent-api.md#consent-categories) are provided: `functional`, `marketing`, `statistics`, `statistics-anonymous` and `preferences`. More categories can be [added via a filter](./filter-reference.md#altisconsentcategories).
Altis does not do any automatic categorisation of your cookies. It provides the means for users to control their consent and for you
to respond to changes in that consent. Determining which scripts fall into which category needs to be manually determined and can
vary by geographic location.

Out of the box, [five categories](./consent-api.md#consent-categories) are
provided: `functional`, `marketing`, `statistics`, `statistics-anonymous` and `preferences`. More categories can
be [added via a filter](./filter-reference.md#altisconsentcategories).

**Note:** `functional` and `statistics-anonymous` categories are always allowed by default. This can be modified using the [`altis.consent.always_allow_categories` filter](./filter-reference.md#altisconsentalways_allow_categories).
**Note:** `functional` and `statistics-anonymous` categories are always allowed by default. This can be modified using
the [`altis.consent.always_allow_categories` filter](./filter-reference.md#altisconsentalways_allow_categories).

## Configuration
Altis Consent is active by default. However, if your project is already using an alternative consent system and you would like to disable Altis Consent, this can be done in the project's `composer.json` file:

Altis Consent is active by default. However, if your project is already using an alternative consent system and you would like to
disable Altis Consent, this can be done in the project's `composer.json` file:

```json
{
"extra": {
"altis": {
"modules": {
"privacy": {
"consent": false
}
}
}
}
"extra": {
"altis": {
"modules": {
"privacy": {
"consent": false
}
}
}
}
}
```

Alternatively, you can use the [`altis.consent.should_display_banner`](./filter-reference.md#altisconsentshould_display_banner) filter or the [admin "Display Cookie Consent Banner" setting](./privacy-settings-page.md#Dispay-Cookie-Consent-Banner) to disable the banner. Note that neither of these two options will completely disable the Consent API itself, and all associated JavaScript will still load on the page.
Alternatively, you can use the [`altis.consent.should_display_banner`](./filter-reference.md#altisconsentshould_display_banner)
filter or the [admin "Display Cookie Consent Banner" setting](./privacy-settings-page.md#Dispay-Cookie-Consent-Banner) to disable
the banner. Note that neither of these two options will completely disable the Consent API itself, and all associated JavaScript
will still load on the page.
30 changes: 22 additions & 8 deletions docs/consent/consent-api.md
View file
Original file line number Diff line number Diff line change
@@ -1,14 +1,21 @@
# Consent API

The Consent API is a developer API to read and register consent categories, to allow consent management and other plugins to work together, improving compliance.
The Consent API is a developer API to read and register consent categories, to allow consent management and other plugins to work
together, improving compliance.

## How does it work?

The Consent API adds two new concepts: a `consent_type` and a consent `category`. Categories are used to group user data by its intended usage, e.g. `marketing`. `consent_type` defines whether consent is `optin`, `optout` or some other type defined in the code.
The Consent API adds two new concepts: a `consent_type` and a consent `category`. Categories are used to group user data by its
intended usage, e.g. `marketing`. `consent_type` defines whether consent is `optin`, `optout` or some other type defined in the
code.

The default consent type can be set in the code. The Altis Consent module defaults the consent type to `optin`, except for the `functional` and `statistics-anonymous` categories. This tells you that user data stored locally should only be used if a user explicitly _allows_ access. If the default `consent_type` is set to `optout`, user data will be assumed to be okay to use unless a user explicitly _disallows_ access.
The default consent type can be set in the code. The Altis Consent module defaults the consent type to `optin`, except for
the `functional` and `statistics-anonymous` categories. This tells you that user data stored locally should only be used if a user
explicitly _allows_ access. If the default `consent_type` is set to `optout`, user data will be assumed to be okay to use unless a
user explicitly _disallows_ access.

The default categories `functional` and `statistics-anonymous` that are allowed by default can be modified using the `altis.consent.always_allow_categories` filter. The example below will make only the `functional` category allowed by default:
The default categories `functional` and `statistics-anonymous` that are allowed by default can be modified using
the `altis.consent.always_allow_categories` filter. The example below will make only the `functional` category allowed by default:

```php
add_filter( 'altis.consent.always_allow_categories', function () {
Expand All @@ -28,18 +35,25 @@ Cookies or any other form of local storage that are used exclusively for statist

* **statistics-anonymous**

Cookies or any other form of local storage that are used exclusively for anonymous statistical purposes (Anonymous Analytics Cookies), that are placed on a first party domain, and that do not allow identification of particular individuals.
Cookies or any other form of local storage that are used exclusively for anonymous statistical purposes (Anonymous Analytics
Cookies), that are placed on a first party domain, and that do not allow identification of particular individuals.

* **marketing**

Cookies or any other form of local storage required to create user profiles to send advertising or to track the user on a website or across websites for similar marketing purposes.
Cookies or any other form of local storage required to create user profiles to send advertising or to track the user on a website or
across websites for similar marketing purposes.

* **functional**

Functional cookies or any other form of local storage are any kind of user data that is required for the proper functionality of a site that cannot be disabled without affecting a user's ability to navigate the site. An example is the cookies that WordPress stores to handle user sign-ins for administrators -- if these cookies were blocked, an administrator would not be able to use the site. In these cases, the technical storage or access is strictly necessary for the legitimate purpose of enabling the use of a specific service explicitly requested by the subscriber or user.
Functional cookies or any other form of local storage are any kind of user data that is required for the proper functionality of a
site that cannot be disabled without affecting a user's ability to navigate the site. An example is the cookies that WordPress
stores to handle user sign-ins for administrators -- if these cookies were blocked, an administrator would not be able to use the
site. In these cases, the technical storage or access is strictly necessary for the legitimate purpose of enabling the use of a
specific service explicitly requested by the subscriber or user.

* **preferences**

Cookies or any other form of local storage that can not be seen as statistics, statistics-anonymous, marketing or functional, and where the technical storage or access is necessary for the legitimate purpose of storing preferences.
Cookies or any other form of local storage that can not be seen as statistics, statistics-anonymous, marketing or functional, and
where the technical storage or access is necessary for the legitimate purpose of storing preferences.

Additional consent categories can be defined within a site's code.
Loading

0 comments on commit 44d01d2

Please sign in to comment.