diff --git a/docs/consent/README.md b/docs/consent/README.md index a2a7949..87fd9cb 100644 --- a/docs/consent/README.md +++ b/docs/consent/README.md @@ -12,13 +12,13 @@ To keep up with the GDPR regulations and your company's privacy and cookie polic ## How does it work? -Altis Consent is an API that is designed to handle how cookies and other types of data stored locally on a user's computer are registered in the code. By creating a registry of cookies and local storage, and defining what those cookies are used for, the API allows the software to intelligently use only those cookies that a user has granted access to. - -In order for this to work, all cookies and local storage used on a site must be registered in the way mentioned in the Altis developer documentation. +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. 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. +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. 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. @@ -29,7 +29,11 @@ The API allows management of third party cookies if it is configured so. See the Altis' personalization features track user data using first-party cookies and are supported by default. ## Does the API help categorize the type of cookies? -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 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). + +**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: @@ -48,4 +52,4 @@ Altis Consent is active by default. However, if your project is already using an } ``` -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. \ No newline at end of file +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. diff --git a/docs/consent/Consent-API.md b/docs/consent/consent-api.md similarity index 75% rename from docs/consent/Consent-API.md rename to docs/consent/consent-api.md index c000f75..1bac81e 100644 --- a/docs/consent/Consent-API.md +++ b/docs/consent/consent-api.md @@ -6,7 +6,15 @@ The Consent API is a developer API to read and register consent categories, to a 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`. This means that user data stored locally will 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: + +```php +add_filter( 'altis.consent.always_allow_categories', function () { + return [ 'functional' ]; +} ); +``` Other consent types can be defined within the code. diff --git a/docs/consent/Filter-Reference.md b/docs/consent/filter-reference.md similarity index 97% rename from docs/consent/Filter-Reference.md rename to docs/consent/filter-reference.md index 13144c7..7c87880 100644 --- a/docs/consent/Filter-Reference.md +++ b/docs/consent/filter-reference.md @@ -1,8 +1,7 @@ # Filter Reference +## `altis.consent.always_allow_categories` -## `altis.consent.allowlisted_categories` - -An array of always allowed consent categories. +An array of always allowed consent categories. Defaults to "functional" and "statistics-anonymous". ### Parameters @@ -10,7 +9,7 @@ An array of always allowed consent categories. ### Source -File: [`inc/namespace.php`](https://github.com/humanmade/altis-consent/blob/master/inc/namespace.php) +File: [`inc/namespace.php`](https://github.com/humanmade/altis-consent/blob/master/inc/namespace.php) ## `altis.consent.consent_settings_fields` @@ -73,7 +72,7 @@ The Altis Privacy page saved options. If you create new options for the Privacy ### Parameters -**`$validated`** _(array)_ An array of validated data. +**`$validated`** _(array)_ An array of validated data. **`$dirty`** _(array)_ An array of unvalidated data. @@ -83,7 +82,7 @@ File: [`inc/settings.php`](https://github.com/humanmade/altis-consent/blob/maste ## `altis.consent.default_banner_message` -The default cookie consent banner message. This is the text that appears in the WordPress WYSIWYG editor on the Altis Privacy page by default, before it's been saved. +The default cookie consent banner message. This is the text that appears in the WordPress WYSIWYG editor on the Altis Privacy page by default, before it's been saved. ### Parameters diff --git a/docs/consent/Function-Reference.md b/docs/consent/function-reference.md similarity index 85% rename from docs/consent/Function-Reference.md rename to docs/consent/function-reference.md index 213bdda..ef121b7 100644 --- a/docs/consent/Function-Reference.md +++ b/docs/consent/function-reference.md @@ -1,13 +1,13 @@ # PHP Function Reference -**Note:** All the functions in the Altis Consent plugin use the `Altis\Consent` namespace except where noted. +**Note:** All functions are in the Altis Consent plugin use the `Altis\Consent` namespace except where noted. ## `load_consent_banner` -Loads the templates used to display the cookie consent banner. The path to the banner can be customized using the [`altis.consent.consent_banner_path`](/Filter-Reference#altisconsentconsent_banner_path) filter. +Loads the templates used to display the cookie consent banner. The path to the banner can be customized using the [`altis.consent.consent_banner_path`](./filter-reference.md#altisconsentconsent_banner_path) filter. * Uses [`load_template`](https://developer.wordpress.org/reference/functions/load_template/) -* See [`altis.consent.consent_banner_path`](/Filter-Reference#altisconsentconsent_banner_path) +* See [`altis.consent.consent_banner_path`](./filter-reference.md#altisconsentconsent_banner_path) ### Example ```php @@ -20,10 +20,10 @@ function render_consent_banner() : string { ## `should_display_banner` -Determines whether the banner should be displayed. Uses the `display_banner` setting defined in the admin but can be filtered by using the [`altis.consent.should_display_banner`](/Filter-Reference#altisconsentshould_display_banner) filter. +Determines whether the banner should be displayed. Uses the `display_banner` setting defined in the admin but can be filtered by using the [`altis.consent.should_display_banner`](./filter-reference.md#altisconsentshould_display_banner) filter. * Uses [`Settings\get_consent_option`](#settingsget_consent_option) -* See [`altis.consent.should_display_banner`](/Filter-Reference#altisconsentshould_display_banner) +* See [`altis.consent.should_display_banner`](./filter-reference.md#altisconsentshould_display_banner) ### Return @@ -43,7 +43,7 @@ function load_consent_banner() { Returns the default consent cookie prefix. -* See [`altis.consent.cookie_prefix`](/Filter-Reference#altisconsentcookie_prefix) +* See [`altis.consent.cookie_prefix`](./filter-reference.md#altisconsentcookie_prefix) ### Return @@ -60,7 +60,7 @@ wp_localize_script( 'altis-consent', 'altisConsent', [ Returns the active consent types. -* See [`altis.consent.types`](/Filter-Reference#altisconsenttypes) +* See [`altis.consent.types`](./filter-reference.md#altisconsenttypes) ### Return @@ -77,7 +77,7 @@ wp_localize_script( 'altis-consent', 'altisConsent', [ Returns a list of active consent categories. -* See [`altis.consent.categories`](/Filter-Reference#altisconsentcategories) +* See [`altis.consent.categories`](./filter-reference.md#altisconsentcategories) ### Return @@ -94,7 +94,7 @@ wp_localize_script( 'altis-consent', 'altisConsent', [ Returns a list of active possible consent values. -* See [`altis.consent.values`](/Filter-Reference#altisconsentvalues) +* See [`altis.consent.values`](./filter-reference.md#altisconsentvalues) ### Return @@ -129,7 +129,7 @@ if ( ! Consent\validate_consent_item( $category, 'category' ) ) { ## `get_cookie_policy_url` -Retrieves the URL to the cookie policy page. Can be filtered by the [`altis.consent.cookie_policy_url`](/Filter-Reference#altisconsentcookie_policy_url) filter. +Retrieves the URL to the cookie policy page. Can be filtered by the [`altis.consent.cookie_policy_url`](./filter-reference.md#altisconsentcookie_policy_url) filter. * Uses [`Settings\get_consent_option`](#settingsget_consent_option) * Uses [`get_post_type`](http://developer.wordpress.org/reference/functions/get_post_type/) @@ -175,7 +175,7 @@ $cookie_expiration = Altis\Consent\Settings\get_consent_option( 'cookie_expirati **Note:** Defined in the `Altis\Consent\Settings` namespace. -Gets the default banner message. Filterable with the [`altis.consent.default_banner_message`](/Filter-Reference#altisconsentdefault_banner_message) filter. +Gets the default banner message. Filterable with the [`altis.consent.default_banner_message`](./filter-reference.md#altisconsentdefault_banner_message) filter. ### Return diff --git a/docs/consent/google-tag-manager.md b/docs/consent/google-tag-manager.md index 7e48010..b7b15f4 100644 --- a/docs/consent/google-tag-manager.md +++ b/docs/consent/google-tag-manager.md @@ -2,7 +2,7 @@ Support for Google Tag Manager is provided via GTM's data layer variable. When either the page loads or consent is subsequently changed the data layer is updated allowing you to create triggers based on the consent given. -The event name is `altis-consent-changed` and the variable is named `altisConsent`. The variable data is a list of the [consent categories](./Consent-API.md#consent-categories) currently given for example "functional, statistics-anonymous". +The event name is `altis-consent-changed` and the variable is named `altisConsent`. The variable data is a list of the [consent categories](./consent-api.md#consent-categories) currently given for example "functional, statistics-anonymous". ## Creating the Variable diff --git a/docs/consent/Privacy-Settings-page.md b/docs/consent/privacy-settings-page.md similarity index 100% rename from docs/consent/Privacy-Settings-page.md rename to docs/consent/privacy-settings-page.md diff --git a/docs/consent/template-architecture.md b/docs/consent/template-architecture.md index c754441..283b750 100644 --- a/docs/consent/template-architecture.md +++ b/docs/consent/template-architecture.md @@ -1,12 +1,12 @@ # Template Architecture -The Altis Consent module comes with a default banner that can be customized via the [filters](/Filter-Reference) provided for the messaging and button text. However, those templates can be replaced entirely or only specific templates can be replaced by your own in a theme or plugin. +The Altis Consent module comes with a default banner that can be customized via the [filters](./filter-reference.md) provided for the messaging and button text. However, those templates can be replaced entirely or only specific templates can be replaced by your own in a theme or plugin. The default banner templates are located in the `/tmpl` directory. ## Overriding the default templates -Overriding the default templates is easy. You can either override all of them using the [`altis.consent.consent_banner_path` filter](/Filter-Reference#altisconsentconsent_banner_path) and defining the path to your main consent banner template file. Or you can override individual templates, keeping the others, by using the filters for the given template path (see below). +Overriding the default templates is easy. You can either override all of them using the [`altis.consent.consent_banner_path` filter](./filter-reference.md#altisconsentconsent_banner_path) and defining the path to your main consent banner template file. Or you can override individual templates, keeping the others, by using the filters for the given template path (see below). ### Example @@ -22,30 +22,30 @@ add_filter( 'altis.consent.cookie_preferences_template_path', get_template_direc ### `consent-banner.php` -The main template file is [`tmpl/consent-banner.php`](https://github.com/humanmade/altis-consent/blob/master/tmpl/consent-banner.php). This file path can be customized with the [`altis.consent.consent_banner_path` filter](/Filter-Reference#altisconsentconsent_banner_path) and is loaded with the [load_consent_banner](/Function-Reference#load_consent_banner) function. +The main template file is [`tmpl/consent-banner.php`](https://github.com/humanmade/altis-consent/blob/master/tmpl/consent-banner.php). This file path can be customized with the [`altis.consent.consent_banner_path` filter](./filter-reference.md#altisconsentconsent_banner_path) and is loaded with the [load_consent_banner](./function-reference.md#load_consent_banner) function. This template loads the [`consent-updated`](#consent-updatedphp), [`cookie-preferences`](#cookie-preferencesphp) (if applicable), and [`button-row`](#button-rowphp) templates. ### `consent-updated.php` -This template displays the "preferences updated" messaging which can be filtered independently with the [`altis.consent.preferences_updated_message` filter](/Filter-Reference#altisconsentpreferences_updated_message). It is located at [`tmpl/consent-updated.php`](https://github.com/humanmade/altis-consent/blob/master/tmpl/consent-updated.php) but the template can be overridden with the [`altis.consent.consent_updated_template_path` filter](/Filter-Reference#altisconsentconsent_updated_template_path). +This template displays the "preferences updated" messaging which can be filtered independently with the [`altis.consent.preferences_updated_message` filter](./filter-reference.md#altisconsentpreferences_updated_message). It is located at [`tmpl/consent-updated.php`](https://github.com/humanmade/altis-consent/blob/master/tmpl/consent-updated.php) but the template can be overridden with the [`altis.consent.consent_updated_template_path` filter](./filter-reference.md#altisconsentconsent_updated_template_path). ### `cookie-preferences.php` -This template pulls in the cookie consent categories from `WP_CONSENT_API::$config`, loops through them, and displays options for users to customize the types of cookie tracking they would like to allow. It uses the [`altis.consent.apply_cookie_preferences_button_text` filter](/Filter-Reference#altisconsentapply_cookie_preferences_button_text) for the "apply changes" button. +This template pulls in the cookie consent categories from `WP_CONSENT_API::$config`, loops through them, and displays options for users to customize the types of cookie tracking they would like to allow. It uses the [`altis.consent.apply_cookie_preferences_button_text` filter](./filter-reference.md#altisconsentapply_cookie_preferences_button_text) for the "apply changes" button. The built-in CSS is designed to display the cookie preferences panel when the cookie preferences button is clicked. When the panel is displayed, the "allow only functional cookies" and "allow all cookies" buttons are hidden in favor of the more granular controls the preferences panel offers. -The template is located at [`tmpl/cookie-preferences.php`](https://github.com/humanmade/altis-consent/blob/master/tmpl/cookie-preferences.php) /Filter-Reference#altisconsentcookie_preferences_template_path). +The template is located at [`tmpl/cookie-preferences.php`](https://github.com/humanmade/altis-consent/blob/master/tmpl/cookie-preferences.php). ## `button-row.php` -This template pulls in the banner message from the options saved on the Altis Privacy page (or displays the [default banner message](/AFunction-Reference#settingsget_default_banner_message)), loads the [`cookie-consent-policy.php`](#cookie-consent-policyphp) template, and displays buttons to "accept all cookies" or "accept only functional cookies". If more granular controls are set in the admin to allow users to select which categories of cookies they want to accept, it will also display a "cookie preferences" button. +This template pulls in the banner message from the options saved on the Altis Privacy page (or displays the [default banner message](./function-reference.md#settingsget_default_banner_message)), loads the [`cookie-consent-policy.php`](#cookie-consent-policyphp) template, and displays buttons to "accept all cookies" or "accept only functional cookies". If more granular controls are set in the admin to allow users to select which categories of cookies they want to accept, it will also display a "cookie preferences" button. -The template is located at [`tmpl/button-row.php`](https://github.com/humanmade/altis-consent/blob/master/tmpl/button-row.php) but the template can be overridden with the [`altis.consent.button_row_template_path` filter](/Filter-Reference#altisconsentbutton_row_template_path). +The template is located at [`tmpl/button-row.php`](https://github.com/humanmade/altis-consent/blob/master/tmpl/button-row.php) but the template can be overridden with the [`altis.consent.button_row_template_path` filter](./filter-reference.md#altisconsentbutton_row_template_path). ## `cookie-consent-policy.php` -This template displays a link to the cookie consent policy. The link is generated by pulling the saved option from the Altis Privacy page. If no cookie policy page has been defined, the template isn't loaded in `button-row.php`. The link text is filterable using the [`altis.consent.cookie_consent_policy_link_text` filter](/Filter-Reference#altisconsentcookie_consent_policy_link_text). +This template displays a link to the cookie consent policy. The link is generated by pulling the saved option from the Altis Privacy page. If no cookie policy page has been defined, the template isn't loaded in `button-row.php`. The link text is filterable using the [`altis.consent.cookie_consent_policy_link_text` filter](./filter-reference.md#altisconsentcookie_consent_policy_link_text). -The template is located at [`tmpl/cookie-consent-policy.php`](https://github.com/humanmade/altis-consent/blob/master/tmpl/cookie-consent-policy.php), but the template can be overridden with the [`altis.consent.cookie_consent_policy_template_path` filter](/Filter-Reference#altisconsentcookie_consent_policy_template_path). \ No newline at end of file +The template is located at [`tmpl/cookie-consent-policy.php`](https://github.com/humanmade/altis-consent/blob/master/tmpl/cookie-consent-policy.php), but the template can be overridden with the [`altis.consent.cookie_consent_policy_template_path` filter](./filter-reference.md#altisconsentcookie_consent_policy_template_path).