Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Jump to bottom

(HDS-2015) Cookie documentation update #1210

Merged
merged 2 commits into from
Mar 6, 2024
+44 −47
Merged

(HDS-2015) Cookie documentation update #1210

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
d236501
(HDS-2015) Cookie documentation update
Riippi Jan 12, 2024
f970202
(HDS-2015) Added documention for hds-2065
NikoHelle Jan 15, 2024
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
4 changes: 1 addition & 3 deletions CHANGELOG.md
View file
Open in desktop
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
Open in desktop
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
Loading