Skip to main content
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 before proceeding.

​
Install the plugin

1

Log into Shopware admin

Access your Shopware admin panel.
2

Install the Voyado extension

Navigate to Extensions > Store, search for “Voyado”, select the extension, and click Add extension, then Install extension.
3

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.

​
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.
1

Log into Engage

2

Navigate to contact attributes

Go to Administration > Config hub > Contacts > Contact attributes.
3

Add the attribute

Select Add attribute and fill in the following:
FieldValue
NameHas account
IdhasAccount
TypeConsent
Choose which panel to display the attribute in, then select Save.

​
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.
An Engage Store can be linked to both a customer and an order, enabling segmentation by country or physical store location.
https://mintcdn.com/voyado-partners/0IxEIB2Y6a--gNYY/icons/developer-link.png?fit=max&auto=format&n=0IxEIB2Y6a--gNYY&q=85&s=36f1df27b0269657d842f3301d440083

Learn more about Engage stores

1

Log into Shopware admin

2

Navigate to Voyado Configuration

Go to Marketing > Voyado Configuration.
3

Select a sales channel

Under Store and Country Mapping, select the sales channel you want to configure.
4

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.
5

Map specific countries

Select Add New Option to map individual countries to Engage stores. Repeat until all required countries are mapped.
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 for accurate validation.
When the plugin is installed, it automatically adds a Voyado Analytics cookie entry under the Marketing consent group in Shopware’s default cookie banner.
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.
Available in app version 2.1.0 and higher.
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.
Call this after the visitor has accepted the relevant consent category:
window.dispatchEvent(new Event('voyadoConsentGranted'));
  1. Create a new Custom HTML tag in GTM.
  2. Add the following code:
<script>
  window.dispatchEvent(new Event('voyadoConsentGranted'));
</script>
  1. Set the trigger to fire when the visitor grants the relevant consent. If you use a data layer event, push it from your CMP:
dataLayer.push({
  event: 'voyado_consent_granted'
});
Then use voyado_consent_granted as the GTM trigger condition for the Custom HTML tag.

​
Verify the setup

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

Confirm the plugin is active

In the Shopware admin panel, navigate to Extensions > My Extensions and confirm the Voyado plugin status is Active.
2

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.
3

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.
4

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.
5

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.
6

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.
7

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.
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.

​
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: 
{# 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.
https://mintcdn.com/voyado-partners/0IxEIB2Y6a--gNYY/icons/developer-link.png?fit=max&auto=format&n=0IxEIB2Y6a--gNYY&q=85&s=36f1df27b0269657d842f3301d440083

Good to know

https://mintcdn.com/voyado-partners/0IxEIB2Y6a--gNYY/icons/developer-link.png?fit=max&auto=format&n=0IxEIB2Y6a--gNYY&q=85&s=36f1df27b0269657d842f3301d440083

Technical details