Introduction to Magento 1 integration
Note
The Magento 1 integration is no longer supported with updates. Updates will only be made for the Magento 2 integration.
Note
This topic is for administrators and developers with administration access rights in Magento 1.
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 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.
- Unpack the ZIP archive containing the installation onto your local PC.
- Establish an FTP connection to your Magento server.
- Copy the app folder to your Magento server.
Note
Test the installation and configuration first in a non-production (live) environment.
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. 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.
introduction-to-magento-1-integration.mdxImporting 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 |
|---|---|---|
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.
Note
The function to add customer attributes (steps 1-7) is not available in Magento Community Edition. Instead, there are third-party extensions available that add this functionality to the browser.
- Select Customers > Attributes > Manage Customer Attributes.
- Click Add New Attribute and define first the Attribute Properties.
- In the field Attribute Code, enter a unique internal name.
- In the Input Type drop-down list, select the desired data type.
Note
The export to Optimizely Campaign only supports the field types Text Field, Text Area, Date and Yes/No.
- Define the further settings for the customer attribute.
- 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.
- Click Save Attribute.
- Select System > Configuration > optivo broadmail.
- 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.
- Click Save Config. The selected attributes are sent to Optimizely Campaign at every HTTP API request.
- 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 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).
Note
An individual template and the content interface are additional functions, subject to a charge, and are not part of the standard scope of supply for the Magento integration. For more information, contact customer support.
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.
Tip
If a 404 error message (Page not found) appears, log out and log back in again.
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, and enter the confirmation page URL for the unsubscription process in the second field.
Tip
The CMS page for the confirmation (Newsletter Confirm Page) or unsubscription (Newsletter Unsubscribe Page) can also be a CMS page created specially for this case.
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.
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.
Note
The transmission domain for the transactional mails must be delegated to Optimizely and also be stored in your Optimizely Campaign client as a transmission domain. The administration of the delegated domains is carried out by Optimizely. Do not use your shop's main domain (example.com), but instead set up a subdomain for transactional mails (transactions.example.com) and delegate this subdomain.
introduction-to-magento-1-integration.mdxConfiguring 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:
- Select System > Transactional mails. Transactional mail templates are now displayed in a table.
Note
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.
- Click Insert New Template and from the Load default template area, select a template; empty templates cannot be created with Magento.
- Select an area schema from the list below. This schema determines the formatting of prices and dates.
- Click Load template to copy the content.
- In Template Information, enter a name for the template. This name is only used internally.
- Select the send with optivo broadmail check box. The two new fields optivo authcode and optivo bmmailid are now displayed.
- In optivo authcode, enter the authorization code for the recipient list that should be used for the transactional mail.
- Open the Optimizely Campaign menu and select Administration > API Overview > Recipient lists.
- 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.
- 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.
- 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.
- Remove the HTML code from the Template content field.
- Enter recipient parameters to transfer with this template to Optimizely Campaign using the following format:
[parameter]={{var order.getOptivoBillingData('[variable]')}}Note
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.
- To add a parameter, start a new line.
- 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]Note
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.
- 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.
Note
To carry out the programming, you need PHP knowledge and knowledge of the Magento object model.
- Click Save Template.
Note
The template is not activated when saved; that is, no transactional mails are sent using it.
- To activate the template and link it to an action, select System > Configuration.
- Locate the Sales section in the menu on the left and click Sales Emails. This displays actions that trigger a transactional mail to be sent.
- 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).
introduction-to-magento-1-integration.mdxConfiguring 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.
Note
To ensure that the clients are correctly allocated in Optimizely Campaign and Magento, contact customer support to help you with the configuration.
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.
introduction-to-magento-1-integration.mdxIntegrating 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
- In the top menu bar, go to the CMS menu item.
- In the Pages overview, go to the Manage content menu item.
- Select Add new page or edit an existing CMS page.
- In the Editor field, enter the following code fragment:
{{block type="core/template" template="newsletter/subscribe.phtml"}}- Click Save, or Publish.
Integrating the subscription form on category pages
- In the top menu bar, go to the Catalog menu item.
- In the Categories overview, go to the Manage categories menu item.
- Select the required category and a client (optional), and go to the Own design tab.
- 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.
- Click Save, or Publish.
Note
Additional integration options
This section listed only the possible integration options from the back-end. The integration can also take place almost everywhere via the Magento template system. These changes require design experience and access to the Magento installation file system.
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.
- Select System > Configuration.
- Click Progress and then Developer.
- 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.
Tip
To prevent these types of conflicts and integration malfunctions, first install your Magento platform with the Optimizely Campaign extension and other extensions being used onto a test system. Then, reproduce a range of different test scenarios there before carrying out the installation in a production environment.