Add cookies to the consent manager

Prerequisites

You should be familiar with the concept of apps.

App Base Guide

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/shopware/trunk/src/Core/Framework/App/Manifest/Schema/manifest-2.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/shopware/trunk/src/Core/Framework/App/Manifest/Schema/manifest-2.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 of cookie 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.

Add translations

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.