The Shopware 6 Extension

36 min

Content

1 Basics and Installation

2 Subscribe and Unsubscribe Setup

3 Configure transactional messages

4 Advanced Configuration

5 Troubleshooting

1 Basics and installation

1.1 Basics

1.1.1 General

This article is intended for administrators and developers with administrator rights in Shopware. The article provides an overview of the Optimizely Campaign extension for Shopware 6. With the Shopware extension, your customers can subscribe and unsubscribe to your newsletter directly in your shop. The extension transfers the customer data obtained during registration from Shopware to Optimizely Campaign, so that you can use the contact information to personalize your campaigns.

You get the following features for Shopware Professional, Professional Plus and Enterprise 6:

Newsletter registration and unsubscription

Transactional mails via the HTTP API

Until Shopware 6.3, extensions are referred to as plugins, only from Shopware 6.4 they are called extensions in the user interface, and the navigation path to the Extensions menu changes. This documentation is based on the newer version Shopware 6.4.

1.1.2 Preparations

To set up the extension in Shopware, contact Optimizely support and request the extension's software package (include the version number of your Shopware system). The structure and fields of the newsletter recipient list are specified by the Shopware integration and cannot be defined individually.

For your transactional messages, Optimizely sets up a separate transaction recipient list for you, the structure and fields of which can be defined by you; please let support know the desired structure and the names of the fields.

If you have multiple sales channels or stores localized in multiple languages, tell Optimizely the number of stores you want to connect to Optimizely Campaign. See Advanced Configuration.

If you integrate multiple stores, you may need the following in Optimizely Campaign:

separate clients for the individual shops

a separate client for your transactional mails

the establishment of a recipient list-based newsletter unsubscription

1.1.3 About opt-in ID and authorization code

In order for Shopware to transfer recipients and field values to Optimizely Campaign, you must store two values in Shopware:

The opt-in ID as the identifier of the opt-in process. The opt-in ID can be found in the Optimizely Campaign menu bar under Administration > API overview > opt-in processes.

The authorization code of your recipient list in Optimizely Campaign, which the customer service has already stored in your client to connect your shop. You can find the authorization code in Optimizely Campaign under Administration > API Overview > Recipient Lists. Select the recipient list and click Manage Authorization Codes. If an authorization code does not already exist for the selected recipient list, click Create Authorization Code.

Attention: Do not confuse the recipient list for your newsletter recipients with the transaction recipient list for your transactional messages. Customer Support sets up two different types of recipient lists for sending newsletters and sending transactional messages (for example, order confirmations, invoices, etc.).

1.2 Procedures

1.2.1 Calling up the My Plugins Page (up to 6.3)

Attention: In the following, this documentation will always talk about My Extensions . If you use Shopware 6.3 or older, My Plugins is meant. Details of the procedures described may vary.

Prerequisites: You are logged in to the admin interface of Shopware 6.3 or older.

On the menu bar, click Settings.

In the left pane of the Settings page, click System.

Click Plugins.

If necessary: Click My Plugins in the left pane of the page.

→ you see the My Plugins page.

1.2.2 Calling up the My Extensions Page (from 6.4)

Prerequisites: You are logged in to the admin interface of Shopware 6.4 or later.

In the menu bar, click Extensions. → child menu items are displayed.

Click My Extensions. → you see the My Extensions page.

1.2.3 Installing the Extension

Prerequisites: You have the extension from Optimizely Customer Care as . zip archive. You see the My Extensions page in Shopware.

Click Upload Extension.

Select the . zip archive that you received from Optimizely. → If the Shopware extension has been successfully uploaded, the Optimizely Campaign extension will appear in the My Extensions list.

In the list of extensions, in the Optimizely Campaign row, click ... → The context menu opens.

Click Install. → After successful installation, the extension is still disabled.

To enable the extension, click

(toggle) on the left side of the row.

→ The extension is installed and enabled.

1.2.4 Uninstalling the Extension

Prerequisites: You see the My Extensions page in Shopware.

In the list of extensions, in the Optimizely Campaign row, click ... -> The context menu opens.

Click Uninstall.

Confirm the action.

→ The extension is uninstalled.

1.2.5 Installing the Update

Prerequisites: You have received an updated version of the Shopware extension from Optimizely Customer Care.

Uninstall the old version (see Uninstalling the Extension).

Install the new version (see Installing the Extension).

2.1 Basics

2.1.1 General

To configure logon and logoff, the following tasks must be performed:

Configure the opt-in message (the login confirmation) in Optimizely Campaign and reference the confirmation link to your store using a field function.

Enter the opt-in ID and authorization code in Shopware.

Activate the use of the double opt-in procedure in Shopware.

Include a registration form in your shop.

To operate and configure multiple stores or localized language versions of your store, see Advanced Configuration.

2.2 Procedures

2.2.1 Setting up opt-in messages in Optimizely Campaign

Context: The opt-in message is set up in such a way that a click on the link sends data to Shopware. Shopware identifies the customer by the hash parameter and the shop/subshop using the shop-id and shop parameters.

Prerequisites: You are signed in to Optimizely Campaign.

In the menu bar, select Campaigns > Opt-in Processes.

Select the opt-in process you want to use to connect your store and click Edit...

On the message node, click Properties.

Click Edit Content... → The email editor opens.

Click the name of the paragraph that contains the sign-up confirmation link. → The content of the paragraph is displayed in the right pane.

In the Text pane, click Source Code.

Replace the included link with the following line of code/field function:

{Double-Opt-In-Link}?hash={customer-id}&shop-id={shop-id}&shop={shop}

You can find the link to replace in the <a> tag between the quotation marks. For example, in the source code, the following link is included in the <a> tag:

<a href="http://srv2.de/subscribe.html">complete registration</a>

Replace the blue link between the quotation marks as follows:

<a href="{Double-Opt-In-Link}?hash={customer-id}&shop-id={shop-id}&shop={shop}">
complete registration</a>

Click Apply > Close > Save and Close.

2.2.2 Storing an opt-in ID and authorization code in Shopware

Context: See also About Opt-In ID and Authorization Code.

Prerequisites: You see the My Extensions page in Shopware.

In the list of extensions, in the Optimizely Campaign row, click ... -> The context menu opens.

Click Configuration.

In the General Settings section, in the Opt-In Id field, enter the opt-in ID.

In the Authorization code field, enter the authorization code of your recipient list.

Click Save.

2.2.3 Activating the double opt-in procedure

Prerequisites: You are logged in to the Shopware admin interface.

In the menu bar, select Settings > Business Events.

Find in the list the event newsletter registration has been registered.

In the row of the event, click ... → The context menu opens.

On the shortcut menu, click Edit.

Click

(toggle switch) labeled Active. → The toggle switch is in the state on (

).

Click Save.

Tip: To display registered newsletter recipients, select Marketing > Newsletter Recipients.

2.2.4 Integrate registration form

Context: The Shopware extension uses Shopware's standard forms for registering newsletter subscriptions. You can integrate the registration form into any shop page.

Prerequisites: You are logged in to the Shopware admin interface.

From the menu bar, select Catalogs > Categories.

Select the store page to which you want to add a sign-up form.

Go to the Layout tab.

Under Layout Assignment, click Change Layout. → The Select Layout window appears.

Select the layout Standard shop page layout with newsletter form and click Apply Layout.

Click Save.

3 Configure transactional messages

3.1 Basics

3.1.1 How it works

Shopware and Optimizely Campaign work together to send transactional messages:

An email template in Shopware sends the variable values of the transaction to Optimizely Campaign via the HTTP API. The variables include, for example, the customer name, the products ordered, the prices, etc.

The values are cached in the transaction recipient list in Optimizely Campaign.

A transactional campaign in Optimizely Campaign uses field functions to insert the variables sent into a draft message. This creates the finished message that is sent to the recipient.

3.1.2 Example of field codes and Shopware

To set up a transactional message that greets customers with your last name and gives the order date, you need the variables salutation, lastname, and orderdate.

These three variable values are sent by Shopware to Optimizely Campaign and written to the mapped fields of your transactional recipient list. To access these values in the fields, add field functions to the message draft in the transactional campaign.

To use a field function, enclose the name of the recipient list field in curly braces in the message body. The text in the draft message might look like this:

Hello {salutation} {lastname}, thank you for ordering from {orderdate}!

This will be displayed later in the sent message as follows:

"Hello Mr. Smith, thank you very much for your order of August 3rd!"

3.1.3 About the field assignment in Shopware

To use the e-mail template in Shopware (see Procedure), you must assign data fields between Shopware and Optimizely Campaign. The Shopware integration of Optimizely Campaign uses the following structure for mapping:

Recipient list box name={{ Shopware variable name }};

Enter the mapping statement in one row per variable and end each row with a semicolon.

Example:

salutation={{ customer.salutation.translated.letterName }};
firstname={{ customer.firstname }};
lastname={{ customer.lastname }};
s-mail={{ customer.email }};
shopname={{ salesChannel.name }};

Note: Make sure that you always map the Shopware variables to be transferred to existing recipient list fields. To set up recipient list fields, contact Customer Care. Check in advance which data/content you need to transfer to Optimizely Campaign and what content you can realize as static text in the transactional campaign.

3.1.4 The field assignment for ordered products

In addition to some simple field assignments, the predefined e-mail template Order Confirmation in Shopware also contains a more complex assignment: All products in an order are written to the orderPositions recipient list field of the transaction recipient list. For this purpose, the following single line in the template is used (line breaks are inserted here for readability):

orderPositions={% for lineItem in order.lineItems %}"
{% if lineItem.pay-load.productNumber is defined %}
{{ lineItem.payload.productNumber|u.wordwrap(80) }}{% endif %}";
"{{ lineItem.quantity }}"; "{{ lineItem.unitPrice|currency(currencyIsoCode) }}";
"{{ lineItem.totalPrice|currency(currencyIsoCode) }}"; "{{ lineItem.label|u.wordwrap(80) }}
{% if lineItem.payload.options is defined and lineItem.payload.options|length >= 1 %},
{% for option in lineItem.pay-load.options %}{{ option.group }}: {{ option.option }}
{%  if lineItem.pay-load.options|last != option %}{{ " | " }}
{%  endif %}{% endfor %}{% endif %}"; {%  endfor %};

The value of the orderPositions variable is defined with a foreach loop that combines the ordered products in a string. The individual columns (order number, quantity, price, total price, article name) are separated by a semicolon, similar to the file format. csv. The separation of the individual products is realized by a character for a line break.

You can customize this line in the email template, but this is usually not necessary. The rendering of the ordered products in transactional messages can also be changed via the field function in Optimizely Campaign (see Creating a field function for products in Optimizely Campaign). If you have any questions, please contact Optimizely support.

3.1.5 Overview of the configuration steps

To configure transactional messages, you must perform the following tasks:

Have Customer Care set up the transaction recipient list.

Create the transactional campaign in Optimizely Campaign.

Configure the email template in Shopware.

Configure the message draft(s) in detail in the transactional campaign.

If necessary: Set up individual transactional emails for multiple stores.

3.2 Procedure

3.2.1 Request Transaction Recipient List

Context: Optimizely Customer Care needs detailed information to set up the transaction recipient list.

Plan which variable values you need from your Shopware system for the transactional messages in Optimizely Campaign

Create a list with all Shopware variables for which you need a corresponding field in your transaction recipient list. Give the fields in the recipient list appropriate names.

Instruct Optimizely Customer Care to set up a transaction recipient list and attach the list you created earlier.

3.2.2 Creating a Transactional Campaign in Optimizely Campaign

Prerequisites: The transactional recipient list for use with the Shopware extension has been set up by customer support.

Create a transactional campaign.

Use the transaction recipient list set up by Optimizely support for use with the Shopware extension.

In the message draft, add the static text that you want.

Insert field functions where you want the contents of the Shopware variables to be located.

3.2.3 Configuring the e-mail template in Shopware

Context: The email template defines which variable values are sent from Shopware to Optimizely Campaign. The Shopware extension includes two functional tempates for transactional messages for demonstration purposes: Customer Registration and Order Confirmation.

Prerequisites: You are logged in to the Shopware admin interface. You know the authorization code of the transaction recipient list (see About Opt-In ID and Authorization Code) and the mailing ID of the transaction campaign (column ID on the Transactional Mails page).

On the menu bar, click Settings.

On the Settings page, click Email Templates.

On the shortcut menu of the email template, click Edit.

To send the template's variables to Optimizely Campaign via the HTTP API, add a checkmark in the Optimizely field.

In the Optimizely authcode field, enter the authorization code of your transaction recipient list in Optimizely Campaign.

In the Optimizely bmMailingId field, enter the mailing ID of the transactional campaign in Optimizely Campaign.

In the Mail Text area, in the Optimizely field, map the Shopware variables to be transferred with the corresponding recipient list fields of your transaction recipient list in Optimizely Campaign (see About the field assignment in Shopware).

Click Save.

3.2.4 Creating a Field Function for Products in Optimizely Campaign

Context: To clearly display the information about ordered products in a transactional message, you must create a special field code in Optimizely Campaign. This turns the string from Shopware into an HTML table.

Prerequisites: The field functions functionality is available in your client (if not, contact support).

From the Optimizely Campaign menu bar, select Administration > Field Codes.

Click Create....

Under General, in the Name field, type a concise name for the new field code (e.g. CSVOrderObjects).

In the Type drop-down list, select Velocity.

In the Contents section, in the Default Replacement tab, in the Default Replacement field, enter the following code as one single line:

<table> <tr> <td>Produkt-ID</td><td>SKU</td><td>Name</td>
<td>Anzahl</td><td>Preis</td> </tr> 
#set ($csvContent = $csv.readFromString($user.data.orderpositions)) 
#foreach($row in $csvContent) <tr> #foreach($item in $row) 
<td> $item </td> #end </tr> #end </table>

Click Save.

Note: If you know HTML, you can customize the layout of the table to suit your needs. See Field functions.

3.2.5 About transactional messages for multilingual shops

If you have configured other sales channels in your Shopware system in addition to your main sales channel or your shop in different languages, you can set up individual templates in several languages for each shop to send transactional messages. You may need separate transactional recipient lists. To do this, please contact support.

For example, you would like to offer the registration confirmation for your newsletter for non-English-speaking recipients in German. Insert the German translation into the transactional campaign and use the corresponding German field functions where the content from the variables supplied by Shopware should be located. If you do not yet have field functions for international parameters in your client, please contact support.

3.2.6 Setting up transactional messages for multilingual shops

Prerequisites: You are logged in to the Shopware admin interface. You know the authorization code of the transactional recipient list (see About Opt-In ID and Authorization Code) and the mailing ID of the transaction campaign (column ID on the Transactional Mails page). You have set up a template for transactional messages in an additional language in Optimizely Campaign (see Transactional messages).

In the Shopware menu bar, select Settings > e-mail templates.

On the shortcut menu of the email template that you want to edit, click Edit.

Select a language from the top drop-down list.

To send the template's variables to Optimizely Campaign using the HTTP API, select the check box next to Optimizely.

In the Optimizely authcode field, enter the authorization code of your transactional recipient list in Optimizely Campaign.

In the Optimizely bmMailingId field, enter the mailing ID of the transactional campaign in Optimizely Campaign.

Click Save.

4 Advanced Configuration

4.1 Basics

This chapter describes how to use the Optimizely Campaign Shopware extension to configure custom opt-in messages and catalog exports, and how to customize front-end messages for the integration. If you want to set up several shops with separate clients for transactional mails or a recipient list-based newsletter unsubscription, please contact Optimizely support.

4.2 Individual opt-in messages and catalog exports

4.2.1 About individual catalog exports

If you want to configure an individual catalog export for a sub-shop or a language version of your shop, you must create a separate feed for the corresponding shop in Shopware. Always assign a new, different file name for the catalog export of a sub-shop or a language version of your main shop (e.g. products_en.csv for English). If you use a file name multiple times, the individual files of the different catalog exports overwrite each other.

4.2.2 Configuring Individual Catalog Export

Prerequisites: You are logged in to the Shopware admin interface.

From the menu bar, select Extensions > My Extensions.

In the context menu of the Optimizely Campaign plugin, click Configuration.

In the Sales Channel drop-down list, select the store you want to configure.

Make the desired settings and click Save.

4.3 Changing Frontend Messages

If you want to change the front-end messages that are displayed to a visitor or a customer of your shop, for example when logging in or out, you can edit the text files of the integration. The Shopware extension supports the localization functions integrated in Shopware and already provides several standard texts in German and English (British English).

Prerequisites: You are logged in to the Shopware admin interface.

Select Settings > phrases.

Click BASE de-DE to edit the German texts, or BASE en-GB to edit the English texts.

Open the context menu for a phrase and click Edit.

Make your changes and click Save.

4.4 Changing and locating the salutation

Context: You can customize the salutation written in the Optimizely Campaign recipient list field salutation for individual sub-stores or language versions of your store.

Prerequisites: You are logged in to the Shopware admin interface.

Select Settings > Salutations.

Open the shortcut menu for a salutation and click Edit.

Make your changes and click Save.

5 Troubleshooting

5.1 Basics

This section describes common sources of error that can occur during the configuration and operation of the Shopware extension. You will also learn how to access the event logs for troubleshooting.

If this section doesn't help you, contact support.

5.2 Common sources of error

Error	Possible Cause	Solution
Customers cannot subscribe to the newsletter.	The firewall of the shop system blocks the connection to Optimizely Campaign.	Check the network configuration of the shop system.
	The authorization code of the recipient list is invalid.	Check the authorization code of the recipient list and create a new authorization code if necessary.
	The opt-in ID is invalid.	Check and correct the opt-in ID.
The catalog export fails.	The firewall of the shop system blocks the connection to Optimizely Campaign.	Check the network configuration of the shop system.
	The SSH private key was stored incompletely or incorrectly.	Re-enter the SSH key.
	The password of the private SSH key has been stored incompletely or incorrectly.	Re-enter the password of the SSH private key.

5.3 Accessing Event Logs

Context: The Shopware integration logs events and executed tasks, such as catalog export. You can use the event logs to find the appropriate sources of error in case of problems.

Prerequisites: You are logged in to the Shopware admin interface.

In the Menu bar, select Settings > System > Event Logs.

Optional: In the context menu of an entry, click Show Details....