OXID eShop integration

This topic gives you an overview of the OXID integration with Optimizely Campaign. The entire recipient management, from registration to the opt-in process through to updating of the recipient data and unsubscriptions, is done in Optimizely Campaign. The OXID integration allows for sending of transactional mails An email triggered by a recipient action (such as an order or purchase) or event (such as an anniversary). It is sent out subsequent to the event. and regular email campaigns via Optimizely's server.

Supported versions

Community Edition	Professional Edition		Enterprise Edition
not supported	4.7	✓	5.0	✓
	4.8	✓	5.1	✓
	4.9	✓	5.2	✓
	4.10	✓	5.3	✓

Client setup

The OXID integration in Optimizely Campaign client The working environment of Optimizely Campaign. A client is a stand-alone and closed system that serves to organize your mailings. Campaign users can use one or more clients for your scenario. is set up by customer support using the following information:

• Recipient data. The client's recipient lists are adjusted so they contain one column per data field; see Newsletter registration.
• Product data. Your message template is configured so that this data is available in the product paragraphs; see Regular campaign emails.
• SSH key. Create a key pair for secure data transfer, and send the public key and key fingerprint to Optimizely; see Transferring files through SCP.
• Sending domain. To send emails via the server, the sending domain must be delegated to Optimizely.

Configuring SMTP

Customer support also configures the SMTP server in your client for sending system emails from the OXID shop. You will receive an SMTP user and password to be stored in the basic settings of your OXID shop. Specify the server smtpapi.campaign.episerver.net as the SMTP server.

In the system mailing used for registration confirmation (opt-in) for customers from your OXID shop, replace the default field function {Double-Opt-In-Link} with the following parameterized string:

{Double-Opt-In-Link}?cl=newsletter&fnc=addme&lang=${user.data.oxlangid}&confirm=
${user.data.confcode}&uid=${user.data.oxid}

Installing the OXID shop integration

You will receive an installation file for the OXID integration. Install this file on the shop server using FTP access.

1. Save the installation package to your PC.
2. Unpack the installation package.
3. Establish an FTP connection to your OXID shop server.
4. Move the unpacked installation package to the root directory of your OXID shop.
5. To make additional image sizes and formats available for product images in mailings, activate the image generation of additional image sizes within OXID. In the http/modules directory of the OXID server, search for the functions.php file. Open this file in an editor, and add the following code to the end of the file:

   // Optimizely Campaign functions
   include_once realpath( dirname( __FILE__ ) . '/optivo/functions.php');

   If you are using an older version as OXID eShop Professional Edition 4.10 or OXID eShop Enterprise Edition 5.3, see Configuring older versions.

6. Activate the Optimizely module in your shop's administration area by selecting Extensions > Modules > optivo and click Activate at the bottom.

   If you are using the Enterprise Edition (EE) of OXID and want to work with multiple clients, you need to activate the Optimizely Campaign module for each shop client individually.

   

Configuring the OXID shop

1. Select optivo broadmail > Settings and select your shop. Or, in the OXID EE version, select the shop that you want to configure.

   

2. Enter the authorization code in the Main tab. This code is required for authentication when transferring registration data to Optimizely Campaign. You can find the code in the Optimizely Campaign client in the Administration > API overview > Recipient lists, then select the recipient list where the registration data is to be transferred, and click Manage authorisation codes.
3. Enter the opt-in ID in the Main tab. You can find the opt-in ID in your Optimizely Campaign client in the Administration > API overview > Opt-in processes tab. Copy the ID of the required opt-in mailing from the list and add this to OXID in the Opt-in ID field.

   

4. Go to Item export and select the language of the exported file. The Export item including variants option only affects the ad-hoc export, and is not required for the configuration. Enter the additional image sizes for the export at the bottom of the panel.

   Activate the option to generate images in the specified sizes during export. If you are using standard image sizes, you do not need to make any modifications.

   Click Generate and upload export file to start an ad-hoc export. Also configure the automatic time-controlled export for data transfer to Optimizely Campaign, to transfer the current data at defined intervals.

   

5. Go to Log export to configure and download the log file for the newsletter subscriptions from the OXID shop. The log file contains recipients whose data cannot be transferred to Optimizely Campaign, such as when a server connection cannot be established. Enter the export period. To include data that was already exported, activate the Include already exported entries option.

   

6. Click Start export to start the log-file generation. When the data is exported successfully, a confirmation message is displayed, along with a link to download the export file (CSV). Each data set in the log file contains a column with a code that indicates the recipient action:
   • C. Recipient changed
   • U. Recipient unsubscribed
   • S. New recipient

   You also can set up an automatic time-controlled export for the log file. However, the recipient data is sent to the configured email address in unencrypted format.

   Do not use the automatic time-controlled export for the log file. The manually initiated ad-hoc export is defined as a standard fallback for the integration, to keep subscribers and unsubscribers that could not be automatically exported up to date.

7. Go to sFTP configuration and enter Username, SSH key, client Ids, and client name. The user name is provided by customer support. The private key of a previously generated key pair must be stored in the SSH key field, see Transferring files through SCP.

   

8. Configure the sending of system emails, for example order confirmations, via the SMTP server. Select Master data > Basic settings > your shop. Or, in the Oxid EE version, select the shop that you want to configure. In the Master tab, enter the SMTP server, the SMTP user and SMTP password. The standard SMTP server is: smtpapi.campaign.episerver.net. The user name and password are provided by customer support.

Transmitting product data

The automatic time-controlled export transmits product data from your OXID shop to Optimizely Campaign at defined intervals.

1. Establish an FTP connection to your OXID shop server.
2. Set up a Cron Job on the server that accesses the file optivo_artikel_export_cron.php at selected intervals, such as once per day. This file is included in the installation package. The Cron Jobs are called up based on the following scheme:

   sudo php [oxidRoot]/http/modules/optivo/optivo_article_export_cron.php [shopId] [exportVariants]

   Replace the term [oxidRoot] with the base URL of your OXID shop, and the term [shopId] with the ID of your shop. Set the term [exportVariants] to a value of 0 or 1 to regulate whether you want to export items including the variants (in this case set the value to 1) or only independent items and main items of a variant (in this case set the value to 0).

For OXID-EE implementations

If your shop is multi-client and you want to do an export for each client, call optivo_artikel_export_cron.php for each shop. Enter the corresponding shop ID for each shop.

In the following example, three shops with IDs 1, 2 and 3 are configured. The base URL in this example is /var/www/oxid. For the shop with ID 1, the export for items including variants is configured. For the other shops, only the export of independent and main items is configured.

sudo php /var/www/oxid/http/modules/optivo/optivo_article_export_cron.php 67 1
sudo php /var/www/oxid/http/modules/optivo/optivo_article_export_cron.php 68 0
sudo php /var/www/oxid/http/modules/optivo/optivo_article_export_cron.php 69 0

Managing recipients

Registering a newsletter

Newsletter registration is done via the online registration form page on your shop. Registration data is transferred to Optimizely Campaign through an HTTP request. The following data fields are transmitted with each data set:

Field name	Data type	Description	Mandatory field
Email	String	Recipient's email address – This field is also the recipient's unique ID	✓
Title	String	Title (Mr/Ms) of the recipient	✘
First name	String	Recipient's first name	✘
Surname	String	Recipient's last name	✘
Language	String	Language of the shop via which the customer has registered	✓ (transferred automatically)
custom	String	Any additional fields	✘
oxlangid	String	Oxid-internal ID for the correct forwarding of the recipient following opt-in or unsubscription	✓ (transferred automatically)
oxid	String	Oxid-internal shop customer ID	✓ (transferred automatically)
confcode	String	OXID-internal test number	✓ (transferred automatically)

Opting in

Before receiving a newsletter, a new recipient must click the activation link in the double-opt-in email, to confirm the email registration. With the OXID integration, you can use an extended double-opt-in process from Optimizely Campaign. The opt-in status is stored with a time stamp in the recipient list in Optimizely Campaign and in the OXID database.

Unsubscribing

The unsubscribe from newsletter option service is prescribed by the regulator. An Unsubscribe link must be included in sent emails. The unsubscription process is controlled via Optimizely Campaign. Alternatively, recipients can be unsubscribed in OXID. The status of your recipients is synchronized between OXID and Optimizely Campaign.

Changing recipient data

Newsletter recipients can change their data via an online form. Changed data is automatically imported into the recipient list, so that this contains updated information.

Sending mailings

Sending system emails

The OXID integration lets you send orders, shipping confirmations, and invoices via the transmission structure of Optimizely Campaign. You can also create transaction emails in OXID.

Sending regular campaign emails

For regular transmissions, Optimizely Campaign contains recipient data and the product data from your OXID shop system. This lets you create regular newsletters, remarketing campaigns, and recommendations for customers and newsletter recipients. You can personalize the mailings using the recipient data, and enhance them with product data, recommendations, and cross-selling and upselling offers. The OXID integration transfers the following product data to Optimizely Campaign:

Field name	Description
id	Oxid-internal product ID
Name	Product name
category	Main product category
isVariant	indicates if the item is a product variant Commerce: a variant or SKU corresponds to a specific product with specific characteristics. For example, a product line of shirts has individual variations/SKUs that include size, color, and collar size. (such as a different color)
oxparentid	In the case of variants (see above), the ID of the associated product
oxartnum	Item number in the OXID shop
oxean	EAN (international item number) of the product
oxshortdesc	Short description of the product
oxprice	Product price
oxthumb	URL to a thumbnail
oxicon	URL to icon image
oxpic1	URL to original image
oxvarminprice	For main items, this field contains the lowest price (such as shirt in different sizes, from 29.99 €)
oxvarmaxprice	For main items, this field contains the highest price (such as T-shirt, from 19.99 to 29.99 €)
URL	Absolute URL for the product's landing page
oxlongdesc	Product description
image1...5	Absolute URLs for the user-defined image sizes according to the settings in the OXID integration (see also Installation and Configuration)

Configuring older versions

To ensure correct functionality of transactional mails An email triggered by a recipient action (such as an order or purchase) or event (such as an anniversary). It is sent out subsequent to the event. when using an earlier version of OXID eShop Professional Edition 4.10 or OXID eShop Enterprise Edition 5.3, you must comment out the following lines of code in the class.phpmailer.php file:

if($this->Sender == '')
 
{ $result .= $this->HeaderLine('Return-Path', trim($this->From)); }
else
{ $result .= $this->HeaderLine('Return-Path', trim($this->Sender)); }

To comment out lines 967-971, add the following characters before and after the code then save the file:

/*
if($this->Sender == '')
 
{ $result .= $this->HeaderLine('Return-Path', trim($this->From)); }
else
{ $result .= $this->HeaderLine('Return-Path', trim($this->Sender)); }
*/