Configuration

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

Before you start

Complete the steps in Prerequisites before proceeding.

Install the plugin

Log into Shopware admin

Access your Shopware admin panel.

Install the Voyado extension

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

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 Customer Engagement side.

Create the hasAccount contact attribute

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

Log into Customer Engagement

Navigate to contact attributes

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

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.

Map sales channels to Customer Engagement stores

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

A Customer Engagement Store can be linked to both a customer and an order, enabling segmentation by country or physical store location.

Learn more about Customer Engagement stores

Log into Shopware admin

Navigate to Voyado Configuration

Go to Marketing > Voyado Configuration.

Select a sales channel

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

Set a fallback Customer Engagement store

Choose the Customer Engagement store to use as a fallback. Any country without a specific mapping will default to this store.

Map specific countries

Select Add New Option to map individual countries to Customer Engagement stores. Repeat until all required countries are mapped.

Shopware does not validate phone numbers in the same way as Customer Engagement. 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.

Trigger via JavaScript

Call this after the visitor has accepted the relevant consent category:

window.dispatchEvent(new Event('voyadoConsentGranted'));

Trigger via Google Tag Manager

Create a new Custom HTML tag in GTM.
Add the following code:

<script>
  window.dispatchEvent(new Event('voyadoConsentGranted'));
</script>

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.

Confirm the plugin is active

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

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.

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.

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.

Verify soft identification (optional)

If your Customer Engagement 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.

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.

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.

E-com partners

Before you start

Install the plugin

Create the hasAccount contact attribute

Map sales channels to Customer Engagement stores

Learn more about Customer Engagement stores

Verify the setup

Troubleshooting cart tracking

What to read next

Good to know

Technical details

​Before you start

​Install the plugin

​Create the hasAccount contact attribute

​Map sales channels to Customer Engagement stores

Learn more about Customer Engagement stores

​Configure cookie consent for web activity tracking

​Triggering consent manually from a third-party CMP

​Verify the setup

​Troubleshooting cart tracking

​What to read next

Good to know

Technical details

Before you start

Install the plugin

Create the hasAccount contact attribute

Map sales channels to Customer Engagement stores

Configure cookie consent for web activity tracking

Triggering consent manually from a third-party CMP

Verify the setup

Troubleshooting cart tracking

What to read next