Magento 1 Extension v2

Engage by Sailthru's latest extension for Magento 1.x is designed to integrate data and email between your Magento store and Engage by Sailthru.

This extension is designed to be a turnkey integration for the vast majority of e-commerce stores built on Magento. It can also be used as a framework to extend Magento and Engage by Sailthru functionality as required. If you are currently using v1 of this extension, see the Migration section in this document. If you are using Magento 2.x, see our compatible extension for that platform version.

 

Features

Email

• Deliver all Magento-initiated emails through Engage by Sailthru, benefitting from enhanced deliverability and the user-specific tracking of opens and link clicks.
• Create custom Engage by Sailthru templates for confirming orders, shipments, customer registration, and newsletter subscription.

Users

• Capture customer purchase data along with Engage by Sailthru campaign attribution
• Add customers who register or login to your site to a Engage by Sailthru list of your choice.
• Add customers who sign up for your newsletter to a Engage by Sailthru list of your choice, hooking into Magento's newsletter module, which allows signups to a single newsletter
• Add or update all Magento customer data in Engage by Sailthru (for new and existing customers) upon each login, purchase, or name/email update

Personalization

• Sync your products to the Engage by Sailthru Content Library for all configured stores
• Auto-tag products for Engage by Sailthru with meta keywords, categories, and product attributes.
• Automatically deploy the Engage by Sailthru Script Tag, which allows pageview-tracking and Site Personalization Manager. Alternatively, use the Horizon JS for legacy script support, prior to migration to the new Engage by Sailthru Script Tag.

 

Migration

If you are currently using v1 of this extension, please reach out to your Customer Success representative to discuss migration strategies before installing v2 in order to ensure compatibility with the following v2 changes:

• You must select a template from Engage by Sailthru for both Abandoned Cart and Order Confirmation.
• The set of fields (a.k.a. vars) that are available for Purchase data has been expanded and existing fields have been renamed. You can find all available order confirmation template vars in this document under Template Vars Reference.
• User fields (a.k.a. vars) have changed. See the Template Vars Reference in this document to view those available in v2.
• If you choose the option to create dynamic "wrapper" email templates to send Magento's fully processed email content, Engage by Sailthru templates are created for each email type and use {content} and {subject} for the respective var names to introduce that content.

 

Installation

First, have your developer download the plugin from GitHub. Instructions how to install the plugin are located in the GitHub repository's README. This code is all you need to have basic functionality working.

 

Setup

Basic Setup

1. After the extension is installed, log in to your Magento Admin Panel.
2. From the System menu, select Configuration.
3. From the side navigation menu, in the Engage by Sailthru section, click Setup. From the setup page, you will be able to enable the plugin, enter your API key, and choose whether to deploy Engage by Sailthru Javascript on your store pages.
4. To enable the extension:
   • In the Enable/Disable section, set Engage by Sailthru Module Enabled to Yes.
5. If you would like all Engage by Sailthru API calls sent as a result of this integration to be logged in your Magento log:
   • In the Enable/Disable section, set API Logging Enabled to Yes. Note: This feature is designed to help developers debug custom functionality, and can expedite help when working with the Engage by Sailthru Support team on any issues.
6. Under API Config, enter the application-specific API Key and API Secret that you requested from your Engage by Sailthru representative. The API URI is automatically set to https://api.sailthru.com and should not be changed.
7. Under JavaScript Deployment, you can specify whether to include a Engage by Sailthru JavaScript tag on the pages of your store and, if so, which version: the latest Engage by Sailthru script tag or the legacy Horizon script tag.
   • If you already have a Engage by Sailthru JavaScript tag manually included on your store's pages, leave this setting off until you have removed that tag to avoid duplicate information being recorded to Engage by Sailthru via multiple tags. Normally, it would then be best to enable this setting to match the version of the Engage by Sailthru JavaScript you are currently using and to do so immediately upon removing the script from your site in order to prevent any gap in recorded onsite user activity.
   • If you choose to use the latest Engage by Sailthru script tag, you will then be required to enter your Engage by Sailthru Customer ID, which you can find on the API and Postbacks Settings page in My Sailthru.
   • If you select the legacy Horizon script tag, you will then be required to enter your Engage by Sailthru Horizon Domain, which you can find on the Domains Settings page in My Sailthru.
8. In the top-right corner, click Save Config. When the page refreshes, you'll either receive a confirmation notice at the top of the page indicating that the API keys were validated and saved, or an error message if there was a problem.

Transactional Email Delivery

From the Engage by Sailthru section in the left-side menu, click Transactionals. The Transactionals page has three sections:

• Transactional - When enabled, will send Magento-initiated emails to your users through Engage by Sailthru--such as order and signup confirmation messages--enhancing deliverability while allowing you to track email clicks and opens.
• Abandoned Cart - When enabled, will automatically send logged-in users a reminder when they have left items in their cart.
• Anonymous Abandoned Cart - When enabled, will automatically send users who are not logged in--but who Engage by Sailthru has identified as one of your known users due to their Engage by Sailthru cookie value--a reminder when they have left items in their cart.

If you enable any of these features by setting them to Yes, additional configuration options are displayed.

Settings for Transactional Email

• Display Engage by Sailthru email delivery error to customers. When enabled, if there is ever an error with delivering email to a customer--for example, the user has opted out of all mail--enabling this will surface a custom message of your choosing to the customer. If, within the message, you encourage users to contact you and inquire about their email status, this feature can be useful to help catch improperly set opt-outs for customers who still want to receive email.
• Delivery error message - The message displayed to users whose transactional send results in an error, if you have enabled the above option to "display Engage by Sailthru email delivery error to customers".
• Magento Template Sender - The email address displayed as the Sender for emails sent from Magento using your predefined Magento templates. The menu contains your Engage by Sailthru-verified sender addresses. If you wish to add another email address, a link is available to bring you to https://my.sailthru.com/verify where you can add new verified emails.
• For any instances of Customer Signup, Newsletter Subscribe, Order Confirmation, or Shipping emails--all the transactional email types that Magento can initiate--you can choose either of the following options. In either case, your email will be sent by Engage by Sailthru.
  • A custom Engage by Sailthru template: The drop-down alternatively allows you to select from all templates you have configured in Engage by Sailthru. For each send, data unique to the send is passed from Magento as template vars which you can surface in your template, for example, the shipping address for the order (shipment.address). You can also include user-specific data that is stored on the profile as a user var, such as the user's default shipping address (defaultShippingAddress).
  • Use Magento Template: For the given type of email, the associated template that you have configured in Magento will be used. The subject line and content body for each send will be passed to Engage by Sailthru. Your Engage by Sailthru account will contain a template--named to match the Magento template and automatically configured by the extension--which simply receives the Magento-rendered subject and body, appends your beacon at the end of the body, and sends the message.

Settings for Abandoned Cart Emails

The Engage by Sailthru Magento Extension allows you to set up two types of Abandoned Cart message: one for logged-in customers and another for users who have been identified as having a user profile in your Engage by Sailthru account based on their Engage by Sailthru cookie value, but who are not logged in. We allow you to configure these separately--for example, using a different time delay or message copy for each--but when configuring either one, the process is the same.  Click the Abandoned Cart or Anonymous Abandoned Cart section header to open it, then, next to Enable [or Enable Anonymous] Abandoned Cart Emails, select Yes. After this you will be provided two more fields.

• Abandoned Cart Template - the pre-existing Engage by Sailthru template to use for your Abandoned Cart sends.
• Abandoned Cart Delay Time - how long to wait before sending the email. For more info on how this works behind the scenes, see the Purchase API documentation.

Content

From the Engage by Sailthru section in the left-side menu, click Content.  This section allows you to enable content hooks so that when you create, update, or delete a product in Magento, its data is updated in your Engage by Sailthru Content Library. If you wish to perform an initial sync of all product data, see the Job API. To enable this functionality and the additional options below, next to Enable update hooks to send content to Engage by Sailthru, select Yes. After enabling hooks you must also decide whether to keep master products, variant products, or both, synchronized with Engage by Sailthru. We define variant products for Magento as simple products that have a parent. For example, the small, blue variant of a shirt. All other product types, including simple products without parents, are considered master products.

• Update Master Products - The extension will add or update each master product in your content library.

• Update Variant Products - The extension will add or update each variant to your content library. For each, Engage by Sailthru will append a hash mark and variant SKU to its URL. (For example, http://example.com/product1.html#123456789.) This setting also requires that you have selected the Engage by Sailthru spider option "preserve fragment". 

Note: If you have both master and variant products in your Magento database, depending on your requirements and your product type configuration, you may choose to send just master products, just variant products, or both. If you select just variant products or both, work with your Marigold representative to ensure you configure your templates to prevent redundant product recommendations. To better personalize content, Engage by Sailthru offers auto-tagging of content a Content Library auto-tagger for our Magento extension. This allows you to automatically pull tags from meta keywords (in the meta tab when looking at a product), a product's categories, and a product's attributes (color, size, gender, etc.). You can enable any or all of this functionality.

• Build tags from Meta Keywords

• Build product tags from product categories

• Build product product tags from product attributes

• • When you enable building tags from product attributes, a new field appears allowing you to select the attributes that may be used to generate tags. You can select all, but you may also choose them individually if you want to prevent some fields from being used for Engage by Sailthru tags.
    

 

User Management

After you finish configuring how you'd like to sync your content with Engage by Sailthru, click save, then move on to the users tab.  Whenever a user logs-in or registers on your site, they will be added Engage by Sailthru. However, this screen allows you to customize that further. Enabling Add all customers to a Engage by Sailthru list will make sure that all customers interacting with your Magento store will be added to a Natural List in Engage by Sailthru. Additionally, Enable Newsletter Hook allows you to hook into Magento's native subscription system, and make sure that whenever someone signs up to the Magento newsletter, that they are being added a Engage by Sailthru Natural List of your choice. List options for both options are auto-populated from Engage by Sailthru.

You can configure Engage by Sailthru's Lifecycle Optimizer to take action each time a user is added to one of those lists, beginning a welcome flow or taking any other available actions of your choosing.

 

User Profile Custom Fields (Vars) Reference

When a user signs up to your Magento store or logs in for the first time after the extension is installed, the following data from the user's Magento profile is added to their Engage by Sailthru user profile as custom fields (a.k.a. vars). Note that all fields will then be actionable in Audience Builder, for example, to find users who signed up via Magento within a given date range. 

Field	Description	Type
magento_id	Magento ID	integer
name	Full name	string
suffix	Name suffix	string
prefix	Name prefix	string
firstName	Fiirst name	string
middleName	Middle name	string
lastName	Last name	string
store	Magento store name	string
customerGroup	Magento customer group	string
created_date	Date that customer was created in Magento	string (YYYY-MM-DD)
created_time	UNIX timestamp of customer's creation in Magento	integer (Unix Timestamp)
defaultBillingAddress	Customer's primary billing address, with each component accessible as an element within an array. (See	array
defaultShippingAddress	Customer's primary shipping address	array

Billing and Shipping Address Array Fields

The defaultShippingAddress and defaultBillingAddress fields (a.k.a. vars) are arrays that you can access from your template code. You can access the entire array by name, or a given element using dot notation (for example, defaultBillingAddress.name). These are useful in shipment and order confirmations. Note that some of these items are also added to the user profile, for future use when communicating with the customer or segmenting with Audience Builder.

Field	Description	Type	Available Scope
.name	Name associated with address	string	template
.company	Company associated with address	string	template
.telephone	Telephone associated with address	string	template
.street1	Address street 1 field	string	template
.street2	Address street 2 field (apartment, etc)	string	template
.city	Address city	string	template, user profile
.state	Address state	string	template, user profile
.state_code	Address state code (OH, NY)	string	template, user profile
.country	Address country	String	template, user profile
.country_code	Address country code (US, FR)	string	template, user profile
.postal_code	Address postal code	string	template, user profile

 

Template Vars Reference

The extension can automatically send all of your emails that are initiated by Magento through Engage by Sailthru, dynamically creating templates in Engage by Sailthru that act as containers for the fully processed email content--subject line and body-- coming from Magento. Beyond those Magento-rendered emails, we also offer the ability to create templates in Engage by Sailthru for Newsletter Signup, Customer Registration, Order Confirmation, and Shipments. If you create your own custom templates in Engage by Sailthru, You can use the var names in this section within those templates to surface user information that was recorded by Magento and added to Engage by Sailthru by the extension.

The extension can automatically send all of your emails that are initiated by Magento through Engage by Sailthru, dynamically creating templates in Engage by Sailthru that act as containers for the fully processed email content--subject line and body-- coming from Magento. Beyond those Magento-rendered emails, we also offer the ability to create templates in Engage by Sailthru for Newsletter Signup, Customer Registration, Order Confirmation, and Shipments. If you create your own custom templates in Engage by Sailthru, You can use the var names in this section within those templates to surface user information that was recorded by Magento and added to Engage by Sailthru by the extension.

The extension can automatically send all of your emails that are initiated by Magento through Engage by Sailthru, dynamically creating templates in Engage by Sailthru that act as containers for the fully processed email content--subject line and body-- coming from Magento. Beyond those Magento-rendered emails, we also offer the ability to create templates in Engage by Sailthru for Newsletter Signup, Customer Registration, Order Confirmation, and Shipments. If you create your own custom templates in Engage by Sailthru, You can use the var names in this section within those templates to surface user information that was recorded by Magento and added to Engage by Sailthru by the extension.

Newsletter Signup

The email Magento sends when someone subscribes via the Magento Newsletter module. This template only has an email variable, as a customer may sign up without registering. However, if a customer is registering as well, the standard registration vars will be available on the user profile. 

Customer Registration

This is the email Magento sends when a customer registers.

Field	Description	Type
registration.name	Name of user registering	String
customer	Customer Info	Array (see user vars)

Order Confirmation

Order confirmations have a var called order, which is an array containing all of the following data:

Field	Description	Type
order.id	Increment ID (e.g. #000000001)	string/int
order.items	visible order items	array
order.adjustments	Tax, Shipping, and Discount if applicable	array with [title:price] pairs
order.tenders	Credit Card type and Amount Ordered	single [title:price] pair if order used a CC, otherwise null
order.name	customer name	string
order.status	Order status	string
order.state	Order state	string
order.created_date	Magento CreatedAt date and time	String (e.g. "2017-05-08 23:20:37")
order.total	Magento order grand total	Float (e.g. 354.7900)
order.subtotal	Magento order subtotal	Float (e.g. 354.7900)
order.couponCode	Magento coupon code	String
order.discount	discount amount	Float (e.g. 354.7900)
order.shippingDescription	Shipping method	String
order.isGuest	Is customer a guest?	boolean (0 or 1)
order.billingAddress	order billing address	address array
order.shippingAddress	order shipping address	address array

 

Shipment

Shipment emails contain an order array field (described above) as well as a shipment array field with the properties listed below.

Field	Descrption	Type
shipment
shipment.id	increment id (e.g. #10000033)	string
shipment.items	Shipment items	array of Shipping Item Var Objects
shipment.created_date	Magento CreatedAt date and time	String (e.g. "2017-05-08 23:20:37")
shipment.trackingDetails	Array of tracking objects (e.g. USPS - #123)	array with [by:number] pairs
shipment.shipmentItems	Shipment items	array of Shipping Items
shipment.comment	Shipment comment	string
shipment.paymentHtml	payment type Html block from Magento	HTML string
shipment.address	Address of shipment	address object

 

Shipping Items

Shipment items are a simple array of objects that resemble the following

Field	Description	Type
title	item name	string
options	array of item options	array of [label:value] pairs