diff --git a/concepts/commerce/content/cookie-consent-management.md b/concepts/commerce/content/cookie-consent-management.md index 0beec7325..b4601176c 100644 --- a/concepts/commerce/content/cookie-consent-management.md +++ b/concepts/commerce/content/cookie-consent-management.md @@ -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 @@ -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 @@ -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 @@ -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. diff --git a/guides/plugins/plugins/storefront/add-cookie-to-manager.md b/guides/plugins/plugins/storefront/add-cookie-to-manager.md index 82f411542..a5dc30404 100644 --- a/guides/plugins/plugins/storefront/add-cookie-to-manager.md +++ b/guides/plugins/plugins/storefront/add-cookie-to-manager.md @@ -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. ::: @@ -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.