> ## Documentation Index
> Fetch the complete documentation index at: https://partner-integrations.voyado.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Configuration

Follow these steps to install the Voyado Shopware plugin, configure the required contact attribute in Engage, map your sales channels, and verify that tracking is working correctly.

## Before you start

Complete the steps in [Prerequisites](/docs/ecom/shopware/prerequisites) before proceeding.

## Install the plugin

<Steps>
  <Step title="Log into Shopware admin">
    Access your Shopware admin panel.
  </Step>

  <Step title="Install the Voyado extension">
    Navigate to **Extensions > Store**, search for "Voyado", select the extension, and click **Add extension**, then **Install extension**.
  </Step>

  <Step title="Activate and configure the extension">
    Go to **Marketing > Voyado Configuration**, copy the **Store ID**, and send it securely to your Voyado team. The team will notify you when the extension is configured on the Engage side.
  </Step>
</Steps>

## Create the hasAccount contact attribute

The `hasAccount` attribute in Engage determines whether a contact is a registered customer or a guest in Shopware. Create it before you begin syncing contacts.

<Steps>
  <Step title="Log into Engage" />

  <Step title="Navigate to contact attributes">
    Go to **Administration > Config hub > Contacts > Contact attributes**.
  </Step>

  <Step title="Add the attribute">
    Select **Add attribute** and fill in the following:

    | Field | Value         |
    | ----- | ------------- |
    | Name  | `Has account` |
    | Id    | `hasAccount`  |
    | Type  | `Consent`     |

    Choose which panel to display the attribute in, then select **Save**.
  </Step>
</Steps>

## Map sales channels to Engage stores

Mapping Shopware sales channels to Engage stores lets you track where customers register and ship orders. This data is available as a filter for automations and segmentation.

<Tip>
  An Engage Store can be linked to both a customer and an order, enabling segmentation by country or physical store location.
</Tip>

<Card title="Learn more about Engage stores" icon="https://mintcdn.com/voyado-partners/0IxEIB2Y6a--gNYY/icons/developer-link.png?fit=max&auto=format&n=0IxEIB2Y6a--gNYY&q=85&s=36f1df27b0269657d842f3301d440083" horizontal href="https://developer.voyado.com/docs/setup/stores" width="128" height="128" data-path="icons/developer-link.png" />

<Steps>
  <Step title="Log into Shopware admin" />

  <Step title="Navigate to Voyado Configuration">
    Go to **Marketing > Voyado Configuration**.
  </Step>

  <Step title="Select a sales channel">
    Under **Store and Country Mapping**, select the sales channel you want to configure.
  </Step>

  <Step title="Set a fallback Engage store">
    Choose the Engage store to use as a fallback. Any country without a specific mapping will default to this store.
  </Step>

  <Step title="Map specific countries">
    Select **Add New Option** to map individual countries to Engage stores. Repeat until all required countries are mapped.
  </Step>
</Steps>

<Tip>
  Shopware does not validate phone numbers in the same way as Engage. Add validation to all phone number fields in your customer registration forms. Voyado recommends using the [Google libphonenumber library](https://github.com/google/libphonenumber) for accurate validation.
</Tip>

## Configure cookie consent for web activity tracking

When the plugin is installed, it automatically adds a **Voyado Analytics** cookie entry under the **Marketing** consent group in Shopware's default cookie banner.

<Warning>
  If you use a third-party cookie banner, you must manually add the **Voyado Analytics** cookie to your consent configuration. It must be categorised under a marketing or tracking-related group and presented to the user with the ability to grant or withdraw consent. Without this, web activity tracking will not function.
</Warning>

### Triggering consent manually from a third-party CMP

<Note>
  Available in app version 2.1.0 and higher.
</Note>

If you use a third-party consent management platform (CMP) such as Consentmanager, OneTrust, Cookiebot, or Google Tag Manager, trigger the `voyadoConsentGranted` browser event after the visitor accepts marketing or analytics cookies.

When this event fires, `voyado.js` sets the `voyado-analytics=1` cookie and initialises tracking without requiring a page reload.

<AccordionGroup>
  <Accordion title="Trigger via JavaScript">
    Call this after the visitor has accepted the relevant consent category:

    ```javascript theme={null}
    window.dispatchEvent(new Event('voyadoConsentGranted'));
    ```
  </Accordion>

  <Accordion title="Trigger via Google Tag Manager">
    1. Create a new **Custom HTML** tag in GTM.
    2. Add the following code:

    ```html theme={null}
    <script>
      window.dispatchEvent(new Event('voyadoConsentGranted'));
    </script>
    ```

    3. Set the trigger to fire when the visitor grants the relevant consent. If you use a data layer event, push it from your CMP:

    ```javascript theme={null}
    dataLayer.push({
      event: 'voyado_consent_granted'
    });
    ```

    Then use `voyado_consent_granted` as the GTM trigger condition for the Custom HTML tag.
  </Accordion>
</AccordionGroup>

## Verify the setup

With the plugin installed and the Voyado team confirmation received, run through the following checks in a test environment.

<Steps>
  <Step title="Confirm the plugin is active">
    In the Shopware admin panel, navigate to **Extensions > My Extensions** and confirm the Voyado plugin status is **Active**.
  </Step>

  <Step title="Verify global tracking data">
    Open any storefront page and inspect the page source. Locate the hidden element with the ID `voyado-tracking-data`. Confirm it carries the correct `data-shop-id`, `data-sales-channel-id`, and `data-language` attribute values for your store.

    If it is missing, the plugin template overrides are not loading correctly.
  </Step>

  <Step title="Verify consent event wiring">
    Using browser developer tools, confirm that accepting cookies dispatches a `voyadoConsentGranted` event and sets the `voyado-analytics` cookie to `1`. Confirm that revoking consent dispatches `voyadoConsentRevoked` and removes the cookie.

    If you are using a third-party CMP, this wiring must be configured in the CMP — not in the Voyado plugin.
  </Step>

  <Step title="Verify contact identification">
    Log in to the storefront with a test customer account and navigate to the account page. Confirm that a `voyado-cid` value is written to the browser's local storage.
  </Step>

  <Step title="Verify soft identification (optional)">
    If your Engage email campaigns use personalised links with the `eclub` parameter, open a test link in a browser where no customer is logged in. Confirm that `voyado-cid` is written to local storage after the page loads.
  </Step>

  <Step title="Test product tracking">
    With consent active and a test contact identified, navigate to a product detail page. In the browser's network panel, confirm a POST request is sent to `/api/v2/shopware/product-tracking`. The request should include the product ID, product number, and session ID.
  </Step>

  <Step title="Test cart tracking">
    Add a product to the cart. Confirm a POST request is sent to `/api/v2/shopware/cart-tracking` approximately 2 seconds after the button click. View the cart page and the checkout confirm page — a tracking call should fire on each. Complete a test order and confirm a final cart-tracking call with an empty product array is sent on the order confirmation page.
  </Step>
</Steps>

<Tip>
  The personalised promotions widget is enabled by the Voyado team in the back-end admin. Contact your Voyado representative to enable or disable it for your store.
</Tip>

## Troubleshooting cart tracking

If cart tracking is not working, the Voyado Twig blocks may not be present in your theme. This can happen when using a custom theme or after modifying theme files.

**Option 1 — Reinstall the app.** This reapplies the template customisations automatically.

**Option 2 — Add the Twig block manually.** Add the following block to your theme's `cart-widget.html.twig`:

```twig theme={null}
{# Extend the default Shopware cart widget template #}
{% sw_extends '@Storefront/storefront/layout/header/actions/cart-widget.html.twig' %}

{# Override the cart widget block to include custom tracking data #}
{% block layout_header_actions_cart_widget %}
    {{ parent() }}

    {# Custom block for tracking cart changes #}
    {% block voyado_layout_header_actions_cart_widget %}
        {% set filtered_cart_items = [] %}

        {% for item in page.cart.lineItems %}
            {% if item.type != 'promotion' %}
                {% set filtered_cart_items = filtered_cart_items|merge([item]) %}
            {% endif %}
        {% endfor %}

        {% set cart_data = filtered_cart_items|json_encode %}
        {# Store Cart Tracking Data #}
    {% endblock %}
{% endblock %}
```

Confirm that the template is correctly placed and loaded in your theme after making this change.

## What to read next

<Card title="Good to know" icon="https://mintcdn.com/voyado-partners/0IxEIB2Y6a--gNYY/icons/developer-link.png?fit=max&auto=format&n=0IxEIB2Y6a--gNYY&q=85&s=36f1df27b0269657d842f3301d440083" href="/docs/ecom/shopware/good-to-know" width="128" height="128" data-path="icons/developer-link.png" />

<Card title="Technical details" icon="https://mintcdn.com/voyado-partners/0IxEIB2Y6a--gNYY/icons/developer-link.png?fit=max&auto=format&n=0IxEIB2Y6a--gNYY&q=85&s=36f1df27b0269657d842f3301d440083" href="/docs/ecom/shopware/technical-details" width="128" height="128" data-path="icons/developer-link.png" />