Add cookies to the consent manager
Prerequisites
You should be familiar with the concept of apps.
Create a single cookie
To add new cookies to the cookie consent manager, you can add a cookies
section to your manifest.xml
. Inside this section, you can add new cookie
elements, as shown in the following example. Note that you don't need a setup
section in your manifest.xml
since extending the Storefront doesn't need a registration nor an own server to run.
// manifest.xml
<?xml version="1.0" encoding="UTF-8"?>
<manifest xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:noNamespaceSchemaLocation="https://raw.githubusercontent.com/shopware/platform/trunk/src/Core/Framework/App/Manifest/Schema/manifest-1.0.xsd">
<meta>
<name>ExampleAppWithCookies</name>
<version>1.0.0</version>
<!-- other meta data goes here -->
</meta>
<cookies>
<cookie>
<cookie>my-cookie</cookie>
<snippet-name>example-app-with-cookies.my-cookie.name</snippet-name>
<snippet-description>example-app-with-cookies.my-cookie.description</snippet-description>
<value>a static value for the cookie</value>
<expiration>1</expiration>
</cookie>
</cookies>
</manifest>
Cookie elements can be configured by adding the following child elements:
cookie
(required): The technical name of the cookie. The value is used to store the cookie in the customer's cookie jar.snippet-name
(required): A string that represents the label of the cookie in the cookie consent manager. To provide translations this should be the key of a Storefront snippet.value
(optional): A fixed value that is set as the cookie's value when the customer accepts your cookie. If unset, the cookie will not be updated (set active or inactive) by Shopware, but passed to the update event.expiration
(optional): Cookie lifetime in days. If unset, the cookie expires with the session.snippet-description
(optional): A string that represents the description of the cookie in the cookie consent manager. To provide translations, this should be the key of a Storefront snippet.
For a complete reference of the structure of the manifest file, take a look at the Manifest reference.
Create a cookie group
When adding multiple cookies through your app it may become handy to group them. This makes it possible for the customer to accept all of your cookies at once and additionally enhances the readability of the cookie consent manager.
To add a cookie group, you can add a groups
section within your cookies
section in your manifest.xml
. In the following example, we use the cookie that we created in the previous section but display it in a cookie group:
// manifest.xml
<?xml version="1.0" encoding="UTF-8"?>
<manifest xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:noNamespaceSchemaLocation="https://raw.githubusercontent.com/shopware/platform/trunk/src/Core/Framework/App/Manifest/Schema/manifest-1.0.xsd">
<meta>
<name>ExampleAppWithCookies</name>
<version>1.0.0</version>
<!-- other meta data goes here -->
</meta>
<cookies>
<group>
<snippet-name>example-app-with-cookies.cookie-group.name</snippet-name>
<snippet-description>example-app-with-cookies.cookie-group.description</snippet-description>
<entries>
<cookie>
<cookie>my-cookie</cookie>
<snippet-name>example-app-with-cookies.my-cookie.name</snippet-name>
<snippet-description>example-app-with-cookies.my-cookie.description</snippet-description>
<value>a static value for the cookie</value>
<expiration>1</expiration>
</cookie>
</entries>
</group>
</cookies>
</manifest>
A group
element consists of three child elements to configure the cookie group. Here is a description of all of them:
snippet-name
(required): A string that represents the label of the cookie group in the cookie consent manager. To provide translations this should be the key of a Storefront snippet.entries
(required): Contains the grouped cookies. It is a collection ofcookie
elements described in the previous section.snippet-description
(optional): A string that represents the description of the cookie group in the cookie consent manager. To provide translations this should be the key of a Storefront snippet.
For a complete reference of the structure of the manifest file, take a look at the Manifest reference.
Snippet handling
As already mentioned in the previous sections, both the cookie
and the group
elements can contain snippet-name
and snippet-description
child elements. Although their values can be strings that will be displayed in the Storefront, the preferred way to set up cookie names and descriptions is to provide Storefront snippets. It gives you and the shop owner the possibility to add translations for your cookie's name and description.
If you are not familiar with setting up Storefront snippets, please refer to our snippet guide.
Reacting to cookie consent changes
As described in the previous section, cookie
elements without a value
element will not be set automatically. Instead, you have to react to cookie consent changes within your JavaScript. Find out how to respond to cookie consent changes in the following article: