Site Personalization Manager Implementation

1. Determine Your Content Source

Some of Sailthru’s 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).

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

SPM 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 Sailthru’s 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 Sailthru API, where you’ll specify the feed, rules, whether to return raw JSON or Sailthru-rendered HTML based on a template, and whether to target specific pages by URL structure and areas by CSS class.

4. Add the Sailthru JavaScript Code

Sailthru offers 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.

Sailthru 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 Sailthru 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 by Sailthru 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 Sailthru 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 Sailthru JavaScript versions (e.g. Horizon) on other pages, is supported. However, having any two Sailthru JavaScript tags on the same page is not supported and will cause problems with Sailthru data tracking and SPM functionality.

To use 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": <id> });</script>

That’s all. Do not include any Custom Mode functions below. All default behavior and values listed for those functions is automatically enabled for Simple Mode.

To use 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, and spidering rules (i.e. whether or not to include the page in the Sailthru Client Library). This function requires your Sailthru Customer ID which can be found in My Sailthru on the API and Postbacks Settings page.

Sailthru.init({"customerId" : customerId, <config keys/values>});
Required Parameter Type Default Description
customerId String Customer ID, for example b682bb3746796686c27164ba015c3da7
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:

  • You must use the personalize function to return section content.
  • Will continue to track pageviews for the current URL, unless you set autoTrackPageview to false You may then use the track  function to manually track a pageview.
autoTrackPageview Bool true When isCustom is set to false, this parameter has no effect. Pageviews are tracked automatically.When isCustom is set to true:

  • If true (default), pageview is tracked for current URL.
  • If false, pageview is not automatically tracked for the current URL. You may use the track function to manually track a pageview.
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 Sailthru should spider the page on which the JavaScript appears. Set this to true to prevent spidering of the page.
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), Sailthru 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.

Sailthru.personalize({ sections: [], vars: {}, <additional parameters>});

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:

  • id: section id (UUID) – required
  • selector: CSS selector present on the page. Include to automatically track the section impression and clicks, and automatically replace the selector with the section’s content. Sections configured to return JSON content cannot be rendered automatically; instead, manually replace the desired selector using the onSuccess function below.
  • onSuccess: function fires when personalize call returns valid response for section and returns parsed JSON for that section. The parsed JSON contains the HTML or JSON returned for that section, the audience list used to generate the HTML/JSON, and the provided section ID and selector.
  • onError: function fires when error occurred with section with any available error response.
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 Sailthru-recommended approach to returning JSON recommendations.
onError Function The function called when Site Personalization Manager 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 Personalization Manager 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'
              }
          });

Note: With the personalize call, the value of the sailthru_content cookie, which tracks the user’s last 16 pageviews on your site, is automatically submitted to Sailthru. This data is used to personalize the display for anonymous users. To convert this data to a new or existing user profile when the user registers or logs in, you will also need to submit this cookie value via a User API call. (See Anonymous User Conversion.)

track function

By default, whether or not you have enabled Custom mode, Sailthru 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 Sailthru 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>

Custom Mode: Personalize Sections with HTML and JSON Content

<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(section.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>

Custom Mode: Manually track pageview, section impression, section click

<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>

5. For e-commerce only: Update the Purchase API Call to Submit sailthru_pc Cookie

A cookie named sailthru_pc records the products displayed by Site Personalization Manager that are clicked by your customers so that Sailthru can attribute those purchases to Site Personalization Manager 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"
    }
}
Top