Site Recommendations Implementation
Contents
Before you begin, ensure that your company has subscribed to Site Recommendations and that it has been enabled. To confirm, you can visit the SPM interface at https://my.sailthru.com/spm. If you are redirected to another page, this means that Site Recommendations has not yet been enabled for your account; please contact your representative for more information on how to get started.
1. Content Source
Some personalization algorithms require feeds as a source for content to display, while others do not, pulling directly from your Content Library (while supporting an optional feed, restricting recommendations to those feed items). Note that most feeds are sourced from the Content Library and offer the opportunity for additional filtering of content. If you will use a feed, you can create one on my.sailthru.com, specifying a source and any meta tags to include/exclude, or you can choose to use an existing feed. In your SPM section template, you then can create a rule to specify which feed and content recommendation algorithm to use. When you create the section, you can set up filters for this feed's content based on custom rules built in the Rule Builder UI, for example, the user's location, gender, preferred pricing level, and/or individual interest profile for 1:1 personalization.You can decide whether to pull the same feed for multiple audiences and filter it differently for each, provide different feeds for different audiences, or use any other combination of feeds, algorithms, rules, and audience lists.
2. Create a Rule
Rules allow a marketer to create sophisticated logic that matches the right content to the right user. There are two types of rules: You can create Basic rules using a simple user interface, or Custom rules using custom Zephyr code. Both methods offer access to powerful personalization algorithms and advanced tag filtering.
3. Create a Section
You can create the section using the my.sailthru.com UI or using the API, where you'll specify the feed, rules, whether to return raw JSON or rendered HTML based on a template, and whether to target specific pages by URL structure and areas by CSS class.
4. Add Sailthru's JavaScript
There are two modes for the JavaScript that you will include on your site. Many clients can use the default Simple Mode, however, if you need to make use of the additional JavaScript functions described in this document, you can enable Custom Mode.
Note that this is a per-page configuration, so you can opt to enable both modes and varying groups of functions or parameters on different pages across your site. Regardless, you should at least include the minimum Simple Mode code on all pages across your site that you wish to track for personalization purposes, even if they do not include an SPM section.
All Overlays functionality is managed in the interface.In addition to the Overlays configuration performed in the interface, for User Signup Overlays, you can add custom JavaScript callback functions to perform additional actions with the email address and/or success/error messages of the user-signup call.|
JavaScript Options |
|
|---|---|
| Simple Mode Default
Behavior when isCustom is set to false |
Custom Mode Capability
Behaviors available when isCustom is set to true. Some features require additional setup as described in this document. |
| Auto-tracking of pageviews, section impressions, and section clicks. |
Manual tracking option available for pageviews, section impressions, and/or section clicks. (Ideal for single-page views, such as infinite scroll, and dynamic single-page sites.) Manual tracking can be enabled individually for all three. For each, auto-tracking is the default. Configure using the track function after enabling manual pageview tracking (in the init function) or manual click and/or impression tracking (in the personalize function). |
|
Section content data is returned when the Page (URL) format specified for the section matches the current page URL. To configure the Page for a section, visit my.sailthru.com/spm. |
Sections are returned when the personalize call on the page specifies the specific section by ID in the sections array. Configure using the personalize function. |
| Sections (if not set to use a JSON template) are displayed automatically, replacing the CSS selector on the page that matches the section's Page Element (as configured at my.sailthru.com/spm). |
Sections (if not set to use a JSON template) are displayed automatically, replacing the page element that has a CSS selector matching the one you specify in the sections array. See the selector parameter in the personalize call. |
| Sections with JSON templates are returned as part of the data in the init function onSuccess and need to be rendered manually. | Sections with JSON templates are returned to the onSuccess function specified in the sections array passed by the personalize call and need to be rendered manually. |
| Only the Page URL and existing user data--the current session's pageviews plus any known profile--can be used to personalize the section. |
Additional custom data from the site visit/page context can also be sent to the template to further customize the onsite experience and augment user profiles. Configure using the personalize function vars parameter. |
| Tags for viewed items (to be recorded as user interests) are those spidered or sent via the Content API. |
Tags for viewed items (to be recorded as user interests) can be manually specified in the JS code. Configure using the track function tags parameter after enabling in the init function. |
Include the JavaScript below on your page(s) after customizing it to your needs. If you already have a legacy JavaScript tag embedded on your site, replace it with the latest code described below on all pages, or at least those pages on which you wish to enable SPM. Note that having the latest JavaScript on some pages, and older JavaScript versions (e.g. Horizon) on other pages, is supported. However, having any two JavaScript tags on the same page is not supported and will cause problems with data tracking and Recommendations functionality.
Simple Mode
Include the following JavaScript on the applicable pages of your site after replacing <id> with your Customer ID.
<script src="https://ak.sail-horizon.com/spm/spm.v1.min.js"></script>
<script>Sailthru.init({ customerId: '<yourID>' });</script>Custom Mode
1. Include the following JavaScript tag on your site. Among the values you pass in the init function, you'll set isCustom to true. Also, replace <id> with your Customer ID.<script src="https://ak.sail-horizon.com/spm/spm.v1.min.js"></script>
<script>Sailthru.init({
customerId: <ID>,
isCustom: true,
<additional parameters and values - see init function table in this doc> });
</script>2. Include any of the additional functions below, customized to your requirements. Their format should match the following, with required items for each function (if called) in bold and placeholder text for you to replace in italics:
Sailthru.personalize({ sections: [], vars: {var keys/values} }); Sailthru.track('pageview', {url: url to track, config keys/values}); Sailthru.track('impression', {sectionId: section to track, config keys/values}); Sailthru.track('click', {sectionId: section to track, config keys/values});
Customize these functions and parameters according to the specifications below. (Note that Single-Line Mode uses the default values for all listed functions and parameters.)
3. Customize these functions and parameters according to the specifications below. (Note that Simple Mode uses all default values listed for these functions and parameters.)
init function
Includes options for manual pageview tracking, manually registering user-interest tags, determining per-page spidering (i.e. whether or not to include the page in the Client Library), and additional processing of User-Signup Overlays' email addresses and the success/failure responses as they are posted. This function requires your Customer ID which can be found in My Sailthru on the API and Postbacks Settings page.Sailthru.init({"customerId" : <i>customerId</i>, <<i>config keys/values>});</i>| Parameter | Type | Default | Description |
|---|---|---|---|
| customerId* | String |
Customer ID, for example b682bb3746796686c27164ba015c3da7 * This is the only required parameter for Sailthru.init. |
|
| isCustom | Bool | false |
If false (default), automatically returns section content for all sections that match the current page URL and tracks a pageview for the current URL. If true:
|
| autoTrackPageview | Bool | true | When isCustom is set to false, this parameter has no effect. Pageviews are tracked automatically.When isCustom is set to true:
|
| useStoredTags | Bool | true | Specify which interest tags to assign to the user based on the item; if true, use existing tags in your Content Library (whether added by the Personalize JS spider or Content API calls); if false, use tags sent in the track('pageview') function. If those are not present, default to sailthru.tags meta tags if they exist on the page. If not, meta keyword tags are used. |
| excludeContent | Bool | false | Determines whether the system should spider the page on which the JavaScript appears. Set this to true to prevent spidering of the page. |
| onSignupSuccess | Function | null |
Callback function invoked when the user submits their email address in a User Signup Overlay and the system responds that the list submission was successful. The function takes one parameter, a dictionary containing the attributes email and response, and vars. To suppress the Post-Click action selected in the Overlays UI (a redirect or message to display) and close the overlay, return 0. |
| onSignupError | Function | null |
Callback function invoked when the user submits their email address in a User Signup Overlay and the system responds that the list submission was successful. Accepts the same parameters as onSignupSuccess. In the event of an error, the Post-Click action selected in the Overlays UI (a redirect or message to display) is suppressed and the overlay is closed, regardless of whether you provide an onSignupError function. This function is most commonly called if user loses connectivity, the service is unreachable, or the server rejects the email address. |
Accessing Overlays Form Data
Access the data you collect in an Overlay using class="sailthru-var", data-var-name, and data-var-attribute in the redirect URL and in the onSignupSuccess function.
For example, adding the following HTML to an Overlay will collect the text inputted by the user at sign up time in the var called name:
<input
type="text"
class="sailthru-var"
data-var-name="name"
data-var-attribute="value"
/>
When a user submits the form, in this example using your name in the var called name, your name will be added as a query string to the redirected URL and as a value in onSignupSuccess:
The redirected URL https://www.example.com/?em=example%40example.com&name=your%20name&source=overlay
Note: email (as em), each data-var-name=data-var-attribute, and source are appended to the query string.
personalize function
This function is only required if you have enabled Custom mode by setting the isCustom parameter to true in the init function. Under the default mode (isCustom=false), the init function call will return section content for all sections that match the current page URL, and a pageview for the current URL will be tracked. The personalize call returns and/or renders section content and allows you to specify which CSS selectors should display which SPM sections. You may also pass vars to the section templates. For sections using HTML templates (Onsite Templates in my.sailthru.com/spm), the system renders the HTML code to the matching CSS selector. For JSON sections, the recommendation data needs to be rendered manually using an onSuccess function. The specified CSS selector is used only for impression and click tracking purposes. Typically, one personalize call per page is sufficient. Multiple sections may be included in the call, each with its own parameters for id, selector, onSuccess, and onError, as described in the table below. However, you can also opt to call personalize multiple times on a page (with a unique sections array each time) if you have multiple sections, but want them to be populated at different times.| Parameter | Type | Default | Description |
|---|---|---|---|
| sections | array of JSON objects | Required. A specification of up to 5 sections to return.Parameters for each object in the array, each representing a section:
|
|
| onSuccess | Function | Whereas the onSuccess function for a specific section in the sections array will return parsed JSON for that section, this instance of onSuccess will return unparsed/raw JSON for all sections specified in this personalize call (if the personalize function is successful).Adding onSuccess callbacks in the sections array is the recommended approach to returning JSON recommendations. | |
| onError | Function | The function called when Site Recommendations encounters an error. In this case, a variable errResp will be populated with an error message. | |
| timeout | Integer | 5000(ms) | Time in milliseconds before Site Recommendations will time out, calling the onError function. If you do not include a timeout, the default of 5000 ms (5 seconds) is used. |
| vars | Object | Set of key-value pairs that will be available to templates of all sections displayed on the page (See "vars object," below.) |
- vars object
- You can pass any custom data as vars, including tag arrays for filtering the content that will populate the section.
- Custom vars are available for use by your Zephyr code, for example, if you pass back the value { gender : 'male' } you can filter products so only gender specific recommendations are returned to the user. The value will be accessible in Zephyr by the key, in this case 'gender'.
- Rules of type 'Simple' that are created using the Rule Builder UI can use four reserved var keys for filtering data. These keywords take an array or comma delimited list of tags - ['tag 1', 'tag 2'] or "tag 1, tag 2".
- include_tags_any - recommendations will include at least one of the listed tags
- include_tags_all - recommendations will include all of the listed tags
- exclude_tags_any - recommendations will be excluded if it has any of the listed tags
- exclude_tag_all - recommendations will be excluded if it has all of the listed tags
- Example:
Sailthru.personalize({ sections: [ { id: <section id for section>, selector: <css selector to replace with section content>, } ], vars: { include_tags_any: ['Pants', 'Shorts'], exclude_tags_all: ['Shirt'], source_var: 'Facebook', gender: 'male' } });
track function
By default, whether or not you have enabled Custom mode, the system will track each pageview as well as section impressions and clicks. To prevent either of these default behaviors, you must first enable Custom mode (set isCustom to true in the init function).- To disable automatic pageview tracking:
- In the init function, set autoTrackPageview to false.
- To disable automatic impression and click tracking for a section:
- In the personalize function's sections array, do not include the css selector for the section.
Once automatic pageview or impression/click tracking are disabled, you can follow the instructions below to include functions to manually track these events. Manually Track a Pageview If you are planning to manually track pageviews, set autoTrackPageview to false in the init function, otherwise pageview tracking will occur automatically based on the current page URL. To manually track a pageview, use the function below.
Sailthru.track('pageview', {
url: <url>,
useStoredTags: <Bool>,
tags: ['example', 'test'],
onSuccess: function() {console.log('trackPageView success note');},
onError: function() {console.log('trackPageView failure note');}
}); | Parameter | Type | Default | Description |
|---|---|---|---|
| url | String | Required. Url to track a pageview for | |
| useStoredTags | Bool | true | set to false to use tags on the page (stored in meta tags sailthru.tags or keywords) instead of tags stored in the Content collection |
| tags | Array | Tags to use for pageview instead of those in content collection (need to set useStoredTags to false to use this) | |
| onSuccess | function | function fires when track call returns 2xx HTTP response | |
| onError | function | function fires when track call returns 4xx or 5xx HTTP response |
Manually Track an Impression If you are planning to manually track section impressions, do not specify a 'selector' for that section in the personalize call, otherwise section impression tracking will occur automatically. To manually track a section impression, include the function below.
Sailthru.track('impression', {
"sectionId": <section id - for JSON section > ,
"urls": <array of urls>,
"onSuccess": function(response) {console.log('Manual track impression - SUCCESS', response);},
"onError": function(response) {console.log('Manual track impression - ERROR', response);}
});| Parameter | Type | Default | Description |
|---|---|---|---|
| sectionId | String | Required. Id of the section to track an impression for | |
| urls | Array | List of urls for each of the pieces of content in the section being tracked | |
| onSuccess | Function | See above | |
| onError | Function | See above |
Manually Track a Click If you are planning to manually track section clicks, do not specify a 'selector' for that section in the personalize call, otherwise tracking of clicks within the section will occur automatically. To manually track a section's clicks, include the function below.
Sailthru.track('click', {
"sectionId" : <section id>,
"url" : <clicked URL>,
"onSuccess" : function(response) {
console.log('Manual track click - SUCCESS', response);
},
"onError" : function(response) {
console.log('Manual track click - ERROR', response);
}
});| Parameter | Type | Default | Description |
|---|---|---|---|
| sectionId | String | Required. Id of the section to track a click for | |
| url | String | Required. Url of content that was clicked | |
| onSuccess | Function | See above | |
| onError | Function | See above |
Example JavaScript Configurations
Simple Mode<script src="https://ak.sail-horizon.com/spm/spm.v1.min.js"></script>
<script>
Sailthru.init({
customerId: <customer id>
});
</script><script src="https://ak.sail-horizon.com/spm/spm.v1.min.js"></script>
<script>
Sailthru.init({
customerId: <customer id>,
isCustom: true
});
Sailthru.personalize({
sections: [
{
id: <section id with HTML (Onsite Template)>,
selector: <css selector to render content, track impressions / clicks>,
},
{
id: <section id for JSON template>,
selector: <css selector to track impressions and clicks>,
onSuccess: function(response) {
const elements = document.querySelectorAll('.json-recs');
const articles = JSON.parse(response.json);
const html = articles.map(article => (`
<li>
<img src="${article.image}" width="176" alt="${article.title}">
<h3>
<a href="${article.url}" title="${article.title}">${article.title}</a>
</h3>
</li>
`));
elements.forEach(element => {
element.innerHTML = html.join('');
});
}
}
]
});
</script><script src="https://ak.sail-horizon.com/spm/spm.v1.min.js"></script>
<script>
Sailthru.init({
customerId: <customer id>,
isCustom: true,
autoTrackPageview: false
});
Sailthru.track('pageview', {
url: <url of page to track>
});
Sailthru.personalize({
sections: [
{
id: <section id for section>,
// no selector provided to manually track impressions / clicks
}
]
});
Sailthru.track('impression', {
sectionId: <section id for section>,
urls: <array of urls, not required>
});
Sailthru.track('click', {
sectionId: <section id for section>,
url: <url that was clicked>
});
</script><script src="https://ak.sail-horizon.com/spm/spm.v1.min.js"></script>
<script>
Sailthru.init({
customerId: <customer id>,
isCustom: true,
autoTrackPageview: true,
onSignupSuccess: function(ev) {
console.log('Signed up ' + ev.email);
console.log('Server replied ' + ev.response);
},
onSignupError: function(err) {
console.log('Failed to sign up ' + err.email);
console.log('Server replied ' + err.error);
}
});
</script><script src="https://ak.sail-horizon.com/spm/spm.v1.min.js"></script>
<script>
Sailthru.init({
customerId: <customer id>,
onSignupSuccess: function (e) {
const user_email = e.email;
//Do something with user_email variable
}
});
</script>5. e-commerce only: Update the Purchase API Call
A cookie named sailthru_pc records the products displayed by Site Recommendations that are clicked by your customers so that the system can attribute those purchases to Site Recommendations when displaying your section stats. When the customer makes a purchase, ensure that this cookie value is submitted to the Sailthru purchase API along with the usual purchase item detail. Example post to the purchase API:{
"email": "user@example.com",
"items": [
{
"qty": 1,
"title": "product1",
"url": "https://www.example.com/product1",
"price": 100,
"id": "id1"
},
{
"qty": 2,
"title": "product2",
"url": "https://www.example.com/product2",
"price": 200,
"id": "id2"
}
],
"cookies": {
"sailthru_pc": "003f54695cfdcf42189a680a030aa4d45d9c230940-1ba3-11e6-860e-0242ac1300080000000000000000000000009c230940-1ba3-11e6-860e-0242ac1300089c230940-1ba3-11e6-860e-0242ac1300080000"
}
}