Skip to content

feat: update cookie hash for current language #2076

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

Open
BrocksiNet wants to merge 2 commits into
base: main
Choose a base branch
from
Open

feat: update cookie hash for current language #2076

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
3d3e958
feat(cookie-management): update docs to new object format
BrocksiNet Jan 20, 2026
6c6fb1c
fix(cookie-consent): clarify cookie-config-hash description in docume…
BrocksiNet Jan 20, 2026
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
22 changes: 13 additions & 9 deletions concepts/commerce/content/cookie-consent-management.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -42,14 +42,14 @@ sequenceDiagram
StoreAPI->>CookieProvider: getCookieGroups()
CookieProvider-->>StoreAPI: Cookie groups + hash
StoreAPI-->>Storefront: Cookie configuration
Storefront->>Storefront: Compare stored hash
alt Hash changed
Storefront->>Storefront: Compare stored hash for current language
alt Hash changed for language
Storefront->>User: Show consent banner
else Hash matches
else Hash matches for language
Storefront->>User: Apply stored preferences
end
User->>Storefront: Make choices
Storefront->>Storefront: Store preferences + hash
Storefront->>Storefront: Store preferences + hash (with language ID)
```

## Cookie Categories
Expand Down Expand Up @@ -107,9 +107,13 @@ The configuration hash is an important feature that helps support GDPR complianc
### Mechanism Details

1. **Hash Generation**: A hash is calculated from all cookie configurations (names, descriptions, expiration times)
2. **Hash Storage**: The hash is stored in the browser as `cookie-config-hash`
3. **Change Detection**: On each visit, the current hash is compared with the stored hash
4. **Re-Consent Trigger**: If hashes differ, all non-essential cookies are removed and consent is requested again
2. **Hash Storage**: The hash is stored in the browser as `cookie-config-hash`. The stored value is an object where the language ID is the key and the cookie hash is the value, for example: `{"019ada128cfb711aa7a0d00f476d5961":"998cdcc090e92b3ecdd057241d0fd01f"}`
3. **Change Detection**: On each visit, the current hash is compared with the stored hash for the current language
4. **Re-Consent Trigger**: If hashes differ for the current language, all non-essential cookies are removed and consent is requested again

::: info
**Domain and Language Handling**: Since cookies are stored per domain by the browser, installations using different domains for different languages don't encounter tracking conflicts. The domain itself serves as the primary separator. The language ID within the hash object is specifically designed to address scenarios where multiple languages are served from the same domain, ensuring proper per-language consent tracking.
:::

### When Hash Changes

Expand Down Expand Up @@ -153,7 +157,7 @@ The cookie consent system itself uses special cookies:
| Cookie | Purpose | Lifetime |
|--------|---------|----------|
| `cookie-preference` | Stores user's consent choices | 30 days |
| `cookie-config-hash` | Tracks configuration changes | 30 days |
| `cookie-config-hash` | Tracks configuration changes per language | 30 days |

### Protected Cookies

Expand Down Expand Up @@ -181,7 +185,7 @@ The cookie consent system exposes its configuration through the Store API endpoi

**Endpoint:** `GET /store-api/cookie/groups`

This endpoint enables headless implementations, custom frontends, and third-party integrations to retrieve cookie configuration and the configuration hash.
This endpoint enables headless implementations, custom frontends, and third-party integrations to retrieve cookie configuration, the configuration hash, and the language ID. The hash is provided as a string, and the language ID is also returned by the endpoint. When stored in the browser's `cookie-config-hash` cookie, both values should be stored as an object where the language ID is the key and the hash is the value, for example: `{"019ada128cfb711aa7a0d00f476d5961":"998cdcc090e92b3ecdd057241d0fd01f"}`

For full API documentation, see the [Store API - Fetch all cookie groups](https://shopware.stoplight.io/docs/store-api/f9c70be044a15-fetch-all-cookie-groups) reference.

Expand Down
8 changes: 6 additions & 2 deletions guides/plugins/plugins/storefront/add-cookie-to-manager.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -142,6 +142,10 @@ Since Shopware 6.7.3.0, cookie configurations include a hash that tracks changes

This helps maintain transparency by re-prompting users when cookie handling changes, supporting GDPR compliance requirements. The hash is automatically calculated from all cookie configurations provided by the `CookieProvider`.

::: info
**Hash Storage Format**: The configuration hash is stored in the browser's `cookie-config-hash` cookie as an object where the language ID is the key and the cookie hash is the value, for example: `{"019ada128cfb711aa7a0d00f476d5961":"998cdcc090e92b3ecdd057241d0fd01f"}`. This enables per-language consent tracking. Since cookies are stored per domain by the browser, installations using different domains for different languages don't encounter tracking conflicts. The language ID is specifically used when multiple languages are served from the same domain.
:::

::: info
While this feature helps with GDPR compliance, shop owners are responsible for ensuring their overall cookie usage, privacy policies, and data handling practices comply with GDPR and other applicable regulations.
:::
Expand All @@ -150,8 +154,8 @@ While this feature helps with GDPR compliance, shop owners are responsible for e

1. Your plugin adds/modifies cookies via the `CookieGroupsCollectEvent`
2. Shopware calculates a hash of the entire cookie configuration
3. The hash is stored in the user's browser
4. On the next visit, if the hash differs, the consent banner appears again
3. The hash is stored in the user's browser as an object where the language ID is the key and the hash is the value (e.g., `{"019ada128cfb711aa7a0d00f476d5961":"998cdcc090e92b3ecdd057241d0fd01f"}`)
4. On the next visit, if the hash differs for the current language, the consent banner appears again
5. Users are informed about changes and can make new choices

This automatic re-consent mechanism helps shop owners maintain transparency about cookie changes.
Expand Down