OXID eShop integration
Note
Available only in Germany, Austria, and Switzerland.
Note
This topic is for administrators and developers with administration access rights in OXID.
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 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 | ✓ |
oxid-eshop-integration.mdxClient setup
The OXID integration in Optimizely Campaign client 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.
Note
To use multiple versions (for example, different shops with the integration need multiple clients or sub-clients), contact customer support.
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.
- Save the installation package to your PC.
- Unpack the installation package.
- Establish an FTP connection to your OXID shop server.
- Move the unpacked installation package to the root directory of your OXID shop.
- 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 functionsinclude_once realpath( dirname( __FILE__ ) . '/optivo/functions.php');Note
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.
- Activate the Optimizely module in your shop's administration area by selecting Extensions > Modules > optivo and click Activate at the bottom.
Note
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.
oxid-eshop-integration.mdxConfiguring the OXID shop
- Select optivo broadmail > Settings and select your shop. Or, in the OXID EE version, select the shop that you want to configure.
- 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.
- 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.
- 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.
- 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.
- 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.
Warning
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.
- 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.
- 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.
oxid-eshop-integration.mdxTransmitting product data
The automatic time-controlled export transmits product data from your OXID shop to Optimizely Campaign at defined intervals.
- Establish an FTP connection to your OXID shop server.
- 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 1sudo php /var/www/oxid/http/modules/optivo/optivo_article_export_cron.php 68 0sudo php /var/www/oxid/http/modules/optivo/optivo_article_export_cron.php 69 0Managing recipients
oxid-eshop-integration.mdxRegistering 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 |
|---|---|---|---|
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.
oxid-eshop-integration.mdxSending 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 (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) |
oxid-eshop-integration.mdxConfiguring older versions
To ensure correct functionality of transactional mails 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)); }*/