Skip to content

Commit

Permalink
Merge pull request #1210 from City-of-Helsinki/HDS-2015-Update-cookie…
Browse files Browse the repository at this point in the history 
…-guidelines

(HDS-2015) Cookie documentation update
  • Loading branch information
@mrTuomoK
mrTuomoK authored Mar 6, 2024
2 parents 860353f + f970202 commit eff57b0
Show file tree
Hide file tree
Showing 5 changed files with 44 additions and 47 deletions.
4 changes: 1 addition & 3 deletions CHANGELOG.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -67,9 +67,7 @@ Changes that are not related to specific components

#### Changed

Changes that are not related to specific components

- [Component] What has been changed
- [CookieConsent] Cookie guidelines recommend using subdomains

#### Fixed

Expand Down
40 changes: 22 additions & 18 deletions site/src/docs/components/cookie-consent/api.mdx
View file
Original file line number Diff line number Diff line change
Expand Up @@ -20,20 +20,20 @@ Common texts, groups and cookie data can be found in <ExternalLink openInExterna

The `contentSource` property lists all content, language options, and callbacks for the component. The given source is merged with the default values from the <InternalLink href="/components/cookie-consent/api#component-properties">content file</InternalLink> to create a content-object.

| Property | Required | Description |
| ---------------------------------------------------------------------------------------------------------------------------- | -------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `siteName` | **Yes** | Cookie consent main heading. |
| `currentLanguage` | **Yes** | Currently selected language. Used for picking translations from the <InternalLink href="/components/cookie-consent/api#component-properties">content file.</InternalLink> Is also set to `content.language.current`. Supported values are `fi`, `sv`, and `en`. |
| `requiredCookies` | No | Required cookies can have partial data or all data described in the table below. Missing texts are auto-filled. See examples below this table: <InternalLink href="/components/cookie-consent/api#required-and-optional-cookies">Required and optional cookies.</InternalLink> |
| `optionalCookies` | No | Optional cookies can have partial data or all data described in the table below. Missing texts are auto-filled. See examples below this table: <InternalLink href="/components/cookie-consent/api#required-and-optional-cookies">Required and optional cookies.</InternalLink> |
| `requiredCookies.groups`, `optionalCookies.groups` | No | List of cookie groups. All cookies must belong to a group. Groups with the property `commonGroup` will be auto-filled from the <InternalLink href="/components/cookie-consent/api#component-properties">content file.</InternalLink> |
| `requiredCookies.groups[].cookies`, `requiredCookies.cookies`, `optionalCookies.groups[].cookies`, `optionalCookies.cookies` | No | List of individual cookies. All cookies must belong to a group or they must have property `commonGroup` or `groupId`. The `groupId` must match `group.id` of a custom group and the `commonGroup` must match groups in the <InternalLink href="/components/cookie-consent/api#component-properties">content file.</InternalLink> Do not give both. |
| `texts` | No | User interface string overrides. By default, strings are fetched from the <InternalLink href="/components/cookie-consent/api#component-properties">content file</InternalLink> and this object overrides one or multiple texts. |
| `language` | No | Overrides for default language options. By default, options are fetched from the <InternalLink href="/components/cookie-consent/api#component-properties">content file</InternalLink> and this object overrides one or more properties. `onLanguageChange` callback is also added here. |
| `onAllConsentsGiven` | No | See Callbacks section below. |
| `onConsentsParsed` | No | See Callbacks section below. |
| `noCommonConsentCookie` | No | Consents are saved to a cookie and this option can prevent showing that cookie in the list of consents. If this is not true, `requiredConsents` are always shown and a common group “sharedConsents” is added to it and also a common cookie “helConsentCookie” to that group. All content for those is in the <InternalLink href="/components/cookie-consent/api#component-properties">content file.</InternalLink> |
| `focusTargetSelector` | No | When the modal is closed or the ESC key is pressed when it is open, the focus must be shifted outside the modal. This defines the element to set focus to with this selector (string). Not needed when modal is not used. Throws an error is not set for modal. |
| Property | Required | Description |
| ---------------------------------------------------------------------------------------------------------------------------- | -------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `siteName` | **Yes** | Cookie consent main heading. |
| `currentLanguage` | **Yes** | Currently selected language. Used for picking translations from the <InternalLink href="/components/cookie-consent/api#component-properties">content file.</InternalLink> Is also set to `content.language.current`. Supported values are `fi`, `sv`, and `en`. |
| `requiredCookies` | No | Required cookies can have partial data or all data described in the table below. Missing texts are auto-filled. See examples below this table: <InternalLink href="/components/cookie-consent/api#required-and-optional-cookies">Required and optional cookies.</InternalLink> |
| `optionalCookies` | No | Optional cookies can have partial data or all data described in the table below. Missing texts are auto-filled. See examples below this table: <InternalLink href="/components/cookie-consent/api#required-and-optional-cookies">Required and optional cookies.</InternalLink> |
| `requiredCookies.groups`, `optionalCookies.groups` | No | List of cookie groups. All cookies must belong to a group. Groups with the property `commonGroup` will be auto-filled from the <InternalLink href="/components/cookie-consent/api#component-properties">content file.</InternalLink> |
| `requiredCookies.groups[].cookies`, `requiredCookies.cookies`, `optionalCookies.groups[].cookies`, `optionalCookies.cookies` | No | List of individual cookies. All cookies must belong to a group or they must have property `commonGroup` or `groupId`. The `groupId` must match `group.id` of a custom group and the `commonGroup` must match groups in the <InternalLink href="/components/cookie-consent/api#component-properties">content file.</InternalLink> Do not give both. |
| `texts` | No | User interface string overrides. By default, strings are fetched from the <InternalLink href="/components/cookie-consent/api#component-properties">content file</InternalLink> and this object overrides one or multiple texts. |
| `language` | No | Overrides for default language options. By default, options are fetched from the <InternalLink href="/components/cookie-consent/api#component-properties">content file</InternalLink> and this object overrides one or more properties. `onLanguageChange` callback is also added here. |
| `onAllConsentsGiven` | No | See Callbacks section below. |
| `onConsentsParsed` | No | See Callbacks section below. |
| `noCommonConsentCookie` | No | Consents are saved to a cookie and this option can prevent showing that cookie in the list of consents. If this is not true, `requiredConsents` are always shown and a common group “sharedConsents” is added to it and also common cookies “helConsentCookie” and “helConsentCookieVersion” to that group. All content for those is in the <InternalLink href="/components/cookie-consent/api#component-properties">content file.</InternalLink> |
| `focusTargetSelector` | No | When the modal is closed or the ESC key is pressed when it is open, the focus must be shifted outside the modal. This defines the element to set focus to with this selector (string). Not needed when modal is not used. Throws an error is not set for modal. |
| [Table 1:ContentSource object properties] |

##### ContentSource examples
Expand All @@ -42,11 +42,15 @@ You can find examples of ContentSource property contents in <Link openInNewTab o

#### CookieDomain

The cookie domain is automatically detected from the site the component is on. By default, the component sets the cookie domain to be the root domain with `*.` This way the cookie consents can be read from all subdomains. For example `*.hel.fi`.
The cookie domain is automatically detected from the site the component is on. By default, the component sets the cookie domain to be `window.location.hostname.` This way, the cookie consents are limited to a single service, which makes the cookie more secure and understandable for the user which cookies are used right here.

If your site domain is included in the [public suffix list](https://publicsuffix.org/) or you do not wish to expose your cookies to subdomains, or you want to set the domain manually for some reason, then use the `cookieDomain` property.
If you want to set the domain manually for some reason, then use the `cookieDomain` property.

Cookies for domains on the public suffix list cannot accept subdomain cookies. E.g. `github.io`.
If the service domain is the top level `hel.fi`, use the `customDomain` property to set the cookie domain to `www.hel.fi`, or it will be readable by all.

Cookies for domains on the [public suffix list](https://publicsuffix.org/) cannot accept subdomain cookies. E.g. `github.io`.

If the `cookieDomain` is manually changed, there might be a scenario where consents are stored in two domains and two sets of consents are found in the `document.cookie`. If the component detects two sets of consents, it will remove both. There is no reliable way of knowing which consents are the latest. After the removal, consents will be asked again.

#### Detailed info about properties

Expand Down Expand Up @@ -140,7 +144,7 @@ The consent banner language is controlled via a language dropdown element. Note

### Saving consents

Consents that the user has given are saved to a `city-of-helsinki-cookie-consents` cookie.
Consents that the user has given are saved to a `city-of-helsinki-cookie-consents` cookie. A version number indicating which version of the component is in use, is stored to a `city-of-helsinki-cookie-consents-version` cookie. The version number has no relation to the stored consents.

Cookies are always strings and consents are stored as a JSON-formatted string such as `{"cookie-id":"true","another-cookie-id":"false"}`.

Expand Down
Loading

0 comments on commit eff57b0

Please sign in to comment.