Magento 1 integration

If you are using Magento 1 as e-commerce platform, you can integrate this with Optimizely Campaign and manage customer data via Optimizely's email marketing platform. 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 Magento 1 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. You can also import product data into Optimizely Campaign to display products in remarketing campaigns and recommendations.

Supported versions

Magento CE		Magento EE
1.7	✓	1.12	✓
1.8	✓	1.13	✓
1.9	✓	1.14	✓

Installation

The installation should be carried out by an administrator or Dev operator. For the integration, you need to install the Optimizely Campaign extension in Magento. You need at least PHP 5.3 and phpseclib 0.3.6 on your Magento server (the official distribution from Version 0.3.6.). You can install this via PEAR: http://phpseclib.sourceforge.net/pear.htm.

Install the Optimizely Campaign extension via the file system. You need an FTP connection to your server to transfer the installation package.

1. Unpack the ZIP archive containing the installation onto your local PC.
2. Establish an FTP connection to your Magento server.
3. Copy the app folder to your Magento server.

Configuring in Optimizely Campaign

When setting up your Optimizely Campaign extension, certain data should be available for the configuration. If you are operating several store views, stores and/or websites with a Magento installation, see Configuring multiple-clients.

Log in to your Optimizely Campaign client and select the required 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.. Copy the following IDs and codes:

• Client ID. Open the Optimizely Campaign menu and select Administration > API Overview > REST API.
• Authorization code. Open the Optimizely Campaign menu and select Administration > API Overview > Recipient lists. Select the required recipient list and click Manage authorization codes. If no code is set up for the selected list, click Create authorization code.
• Opt-in ID. Open the Optimizely Campaign menu and select Administration > API Overview > Opt-in processes. Select the opt-in process that you want to use for the Magento store (see following section).
• Opt-in link. Edit the system mailing you are using for the registration confirmation (opt-in) of customers from your Magento shop and replace the default field function for the opt-in link: {Double-Opt-In-Link} with the parameterized string: {Double-Opt-In-Link}?id={bmecssid}&code={bmecsscc}

Customer support will further configure in Optimizely Campaign. Optimizely needs the following information from your Magento shop:

• The IP address of your Magento shop. This is stored in your client.
• Forwarding email address. Should be an administrative email address to where ARF reports, bounces, spam, auto-replies and responses are sent.
• The transmission domain of your shop. Must be delegated to Optimizely and stored in your client as a transmission domain.

Importing recipient data

When setting up the integration, customer support sets up a recipient list with the standard fields from Magento in your Optimizely Campaign client. The recipient list contains the following fields:

Field name	Data type	Description
email	String	Email address
salutation	String	User's title
firstname	String	First name
lastname	String	Last name
language	String	ISO code for the language from the StoreView via which the user has registered.
street	String	Street address
zip	String	Postcode or international ZIP code
city	String	City
state	String	State
country	String	Country

Apart from the mandatory email address and automatic language, fields are optional. To receive the data, create an expanded subscription form or an edit-profile form and integrate this into your shop pages.

Adding and exporting additional recipient data fields

In Magento, you can add recipient data called customer attributes to save with the default recipient data and export the data to Optimizely Campaign. Customer attributes let you adapt your sales approach. You can use customer attributes like any other default value to personalize newsletters or to create highly customized customer segments.

1. Select Customers > Attributes > Manage Customer Attributes.
2. Click Add New Attribute and define first the Attribute Properties.
3. In the field Attribute Code, enter a unique internal name.
4. In the Input Type drop-down list, select the desired data type.

   The export to Optimizely Campaign only supports the field types Text Field, Text Area, Date and Yes/No.

5. Define the further settings for the customer attribute.
6. Click the Manage Label/Options tab and define the titles for the customer attribute, as you want them to be displayed in the admin back end and in the different languages of your shop. You must enter a title in the Admin field. If you leave the other fields empty, the Admin value is used for them as a default value.
7. Click Save Attribute.
8. Select System > Configuration > optivo broadmail.
9. Open the HTTP-API panel and, in the the Customer Attributes to optivo list, select customer attributes you want to export to Optimizely Campaign. Use CTRL to select multiple attributes.
10. Click Save Config. The selected attributes are sent to Optimizely Campaign at every HTTP API request.
11. To process the sent data, communicate the field names and types of the customer attributes to customer support who configure the recipient lists in your Optimizely Campaign client. When this is done, you can access the customer attributes in Optimizely Campaign as a recipient field and can be used to create personalized content or target groups Subset of recipients defined by rules and conditions and a logic relationship between them. For example, all recipients in the United Kingdom. based on these data.

Importing product data into a template

If you are configuring the product data export in Magento, you need a correspondingly equipped message template with a content interface to integrate the imported data into your mailings (for example in the form of recommendations or cross and upselling offers).

The Magento integration transfers the following product data to Optimizely Campaign:

Field name	Data type	Description
id	Long	Product ID
name	String	Product title
category	String	Product category (final path)
description	String	Product description
short_description	String	Short description of the product
sku	String	Item number
product_url	String	URL to product landing page
price	String	Product price
special_price	String	Special price
special_from_date	String	Offer valid from
special_to_date	String	Special valid until
base_image	String	Product image
small_image	String	Downsized product image
thumbnail	String	Thumbnail image

Configuring in Magento

Open the system configuration tool in Magento, then, in the optivo menu, select the menu item optivo broadmail.

General

Open the General area and complete the fields using the data that you copied from your Optimizely Campaign client in the previous step:

• Client ID. Client ID
• Client Name. Optionally, enter the name of your Optimizely Campaign client. This is used for orientation purposes, because the client ID can be difficult to remember.
• Authorization Code. Authorization code
• Opt-in ID. Opt-in ID

HTTP API

Open the HTTP-API area, enter the confirmation page URL for the double opt-in A practice in which a recipient consents to receiving email from the sender before any promotional email is sent. Recipients receive an email with a double opt-in link, which they must click to confirm their interest., and enter the confirmation page URL Stands for "Uniform Resource Locator". Also known as a web address such as http://world.optimizely.com. for the unsubscription process in the second field.

SMTP API

Open the SMTP-API area and select whether you want to use the Optimizely Campaign SMTP-API to send transaction mails. If you have select Yes here, enter the appropriate data in the following fields:

• User name of the API user. Provided by customer support.
• Password of the API user. Provided by customer support.

You also have to configure the Store Email Addresses in Magento. Open the Store Email Addresses menu item and, for the email addresses specified here, specify the domain you have delegated to Optimizely during the SMTP setup.

FTP API

Open the FTP-API (Product Export) area and select whether you want to activate the product data export as per Optimizely Campaign. If you select Yes here, fill in the following data fields with the corresponding information:

• User name of the API user. This is provided by customer support.
• Private key is encrypted. Select Yes from the list of options.
• Private key. A key pair must be generated for data exchange via SFTP. See FTP access via SCP. Enter the private key here and inform Optimizely of the public key.
• Daily Export at. Select the time at which the daily product data export should take place.

  

Transactional mail address

In the System configuration, in the General menu, select the Store email addresses menu item. Open the mailing address that you want to use for your transactional mails via Optimizely Campaign and enter a sender name and a sender address. The mailing address Sales representative is used as standard for transactional mails (for example, order confirmations). You can also configure a different mailing address (such as Adapted email 1). To store this mailing address for transactional mails, go to the Sales emails menu item in the Sales area, and select the corresponding mailing address for each sales campaign.

Configuring transactional mails

You can configure and send a transactional mail for shop actions (orders, shipments, changes to customer and shipping data and so on) using Optimizely Campaign. Adjust or set up corresponding templates in your Magento shop to do this. To create a template:

1. Select System > Transactional mails. Transactional mail templates are now displayed in a table.

   The Template Type column shows whether a template is configured for sending using the Magento shop (template type: HTML) or using Optimizely Campaign (template type: optivo). You can change the template type so that templates, that are configured for sending via the Magento shop, are sent using Optimizely Campaign. To do so, go to step 6.

2. Click Insert New Template and from the Load default template area, select a template; empty templates cannot be created with Magento.
3. Select an area schema from the list below. This schema determines the formatting of prices and dates.
4. Click Load template to copy the content.
5. In Template Information, enter a name for the template. This name is only used internally.
6. Select the send with optivo broadmail check box. The two new fields optivo authcode and optivo bmmailid are now displayed.
7. In optivo authcode, enter the authorization code for the recipient list that should be used for the transactional mail.
   1. Open the Optimizely Campaign menu and select Administration > API Overview > Recipient lists.
   2. Select the required recipient list and click Manage authorization codes. A new window opens that displays a list of authorization codes for the selected recipient list.
   3. Copy the ID of the desired authorization code and enter it into the corresponding field in Magento. If no authorization code is currently available, click Create authorization code to generate a new code.

8. In optivo bmmailid, enter the ID of the transactional mail in Optimizely Campaign that you want to send with this transaction. The transactional mail must be set up in your Optimizely Campaign client beforehand; see Transactional mails.
9. Remove the HTML code from the Template content field.
10. Enter recipient parameters to transfer with this template to Optimizely Campaign using the following format:

    [parameter]={{var order.getOptivoBillingData('[variable]')}}

    Replace the string [parameter] with the name of the parameter in Optimizely Campaign, and replace the string [variable] with the name of the variable used by Magento for the order object. For example, the line lastname={{var order.getOptivoBillingData('lastname')}} sends the last name of the recipient to Optimizely Campaign. See Recipient and billing data for a list of recipient parameters.

11. To add a parameter, start a new line.
12. In addition to the variables provided by the function getOptivoBillingData, you can also send the shop-specific standard variables to Optimizely Campaign to use them in the transactional mail. Use the following format to do this:

    [parameter]=[variable]

    For each variable to be transferred, a corresponding field [parameter] is required in the target recipient list in Optimizely Campaign. To insert a variable, click Insert Variable... and select the desired variable from the list. For example, the line: resetPassword={{htmlescape var=$customer.password}} sends a new password to the resetPassword field. This lets you send a transactional mail to a recipient who has requested a new password.

13. Likewise, enter order items that you want to send with this template to Optimizely Campaign using the following format:

    orderPositions={{var order.getOptivoProducts('product_id','sku','name','price','qty_ordered)}}

    The five standard parameters (product ID, order number, name, price and quantity) are sent using the above format. If you do not require one of these parameters, you can remove it from the schema. If you want to send additional order parameters, you need to program a custom template. See Order details for a list of available order parameters and notes about templates.

    To carry out the programming, you need PHP knowledge and knowledge of the Magento object model.

14. Click Save Template.

    The template is not activated when saved; that is, no transactional mails are sent using it.

    

15. To activate the template and link it to an action, select System > Configuration.
16. Locate the Sales section in the menu on the left and click Sales Emails. This displays actions that trigger a transactional mail 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. to be sent.
17. Open the panel for the desired action and select the desired template from the drop-down list (there is a template for each registered user and guest).

    

Configuring multiple clients

Magento and Optimizely Campaign provide the option of displaying multiple clients. Configure each individual client exactly as described in the configuration sections. Ensure that the clients are allocated correctly in Optimizely Campaign and Magento.

For each client, you need the client ID, client name, authorization code and opt-in ID. You can configure the confirmation pages for the opt-in and the unsubscription confirmation separately for each client, or you can use the same URLs for clients. The configuration for the SMTP-API and the FTP-API is global, and only needs to be carried out once.

Selecting a client in Magento

Clients are depicted in Magento via websites, stores and store views. See User Guide from Magento. The client selection section is at the top left-hand side of the configuration.

Integrating the subscription form

Subscription to your newsletter is performed via the online registration form on your shop pages. The registration data is transferred to Optimizely Campaign by means of an HTTP request. The standard template for the subscription form can be integrated onto any CMS page. Connection to Optimizely Campaign is automatic when you are using the standard template. For standard newsletter subscriptions, only the email address is requested in the standard form. Magento also automatically transfers to Optimizely Campaign the language in which new subscribers are registered in the Magento shop. You can use this information to send newsletters in different languages, for example.

To request additional recipient data, you need an extended subscription form. For this type of form, you need extended programming knowledge in HTML. See Importing recipient data for information about the data that you can request and process with the integration.

Integrating the subscription form on a CMS page

1. In the top menu bar, go to the CMS menu item.
2. In the Pages overview, go to the Manage content menu item.
3. Select Add new page or edit an existing CMS page.
4. In the Editor field, enter the following code fragment:

   {{block type="core/template" template="newsletter/subscribe.phtml"}}

5. Click Save, or Publish.

   

   

Integrating the subscription form on category pages

1. In the top menu bar, go to the Catalog menu item.
2. In the Categories overview, go to the Manage categories menu item.
3. Select the required category and a client (optional), and go to the Own design tab.
4. Enter the following code fragment in the Editor field. Your subscription may have a different column layout and positioning, so adjust accordingly.

   <!-- Newsletter Box -->
   <reference name="right">
   <block type="newsletter/subscribe"
   name="right.newsletter"
   template="newsletter/subscribe.phtml"/>
   </reference>

   This code fragment integrates the subscription form into the right-hand layout column. If you want to integrate the newsletter into the left-hand column, replace the tag

   <reference name="right"> with the tag <reference name="left">

   and replace the attribute name="right.newsletter" with name="left.newsletter".

   Depending on the integration and to ensure a correct display on different end devices, you also may make changes in CSS.

5. Click Save, or Publish.

   

   

Error handling

Activating Magento logging

By default, general logs are written to the system.log file, and errors and exceptions to the exception.log file. You can change these file names at var/log/.

Activate writing log files in Magento for error analysis.

1. Select System > Configuration.
2. Click Progress and then Developer.

   

3. Set the Enabled option to Yes.

Activating developer module

To analyze errors and ensure that effective logging is taking place, activate the developer mode in Magento via .htaccess or directly in the index.php of Magento:

The log file for the Optimizely Campaign extension is located in the /var/log/ directory within the Magento installation. The name of the log file is optivo_broadmail.log.

Conflicts with other Magento extensions

There may be conflicts between the Optimizely Campaign extension and other extensions if these extend the same Magento core functions. In particular, conflicts may occur in connection with other Magento extensions that also provide newsletter, SMTP or similar functions to the Optimizely Campaign extension.

Furthermore, local code adjustments in the code pool local can lead to additional by-effects or side effects in the interplay.

During error analysis, pay attention to which extensions and in-house developments are integrated in the Magento installation.