Site Personalization Manager Implementation

1Prepare a Content Feed (Optional)

Some of Sailthru’s personalization algorithms require feeds, other algorithms do not (pulling directly from your Content Library), however, those algorithms can also be combined with a complementary feed. If a feed is defined, the algorithm will be restricted to recommending from the items in the feed.

The personalize() Zephyr function in your template will specify the algorithm and optional feed.

If you will use a feed, you can create one on my.sailthru.com with the desired content set for personalized display. You can also choose to use an existing feed.

When you create the section, you can set up filters for this feed’s content based on custom rules, 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, template rules, and audience lists.

2Create 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.

3Create 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 rendered HTML based on a template, and whether to target specific URL structures and CSS classes.

4Add the Personalize JavaScript Code

Sailthru offers two modes for the Personalize JavaScript that you must include on your site. Most clients can use the default Single-Line Mode, however, if you need to make use of the additional JavaScript functions described in this document, you can enable Instrumented Mode.

Use the following feature-comparison table to decide.

Sailthru Personalize JS Mode Features
Single-Line Mode (Default) Instrumented Mode
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.
Section displayed automatically when the current URL format and displayed CSS selector match the section definition. Section displayed automatically, or when JS call on the page specifies a Sailthru section ID and ID of the HTML element within which to display it.
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.
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.

Note that this is a per-page setting, so you can opt to enable both modes on different types of pages across your site. Regardless, you should at least include the default Single-Line code on all pages across your site that you wish to track for personalization purposes, even if they do not include a SPM section. If you already have legacy Sailthru JavaScript code embedded on your site, you can replace it with the latest version of the Personalize JS.

To use Single-Line Mode

Include the following JavaScript on your site.

<script src="//ak.sail-horizon.com/onsite/personalize.v0.0.4.min.js"
type="text/javascript"></script>

That’s all. Do not include the Instrumented Mode functions below. All default behavior and values listed for those functions is automatically enabled for Single-Line mode.

To use Instrumented Mode

1. Include the following JavaScript on your site. Be sure to include the data-sailthru-setup attribute, set to “true”.

<script src="//ak.sail-horizon.com/onsite/personalize.v0.0.4.min.js"
type="text/javascript" data-sailthru-setup="true"></script>

2. Include the functions below, customized to your requirements. Their format should match the following, with required items in bold and placeholder text for you to replace in italics:

<script type=”text/javascript”>
   Sailthru.SPM.setup(customerId, {config keys/values});
   Sailthru.SPM.addSection(sectionId, {config keys/values});
   Sailthru.SPM.trackPageView(url, {config keys/values});
   Sailthru.SPM.trackImpression(sectionJSONId, url, {config keys/values});
   Sailthru.SPM.trackClick(sectionJSONId, url, {config keys/values});
   Sailthru.SPM.personalize({config keys/values});
</script>

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

setup function

Includes options for manual pageview tracking and manually registering user-interest tags. This function requires your Sailthru Customer ID which can be found in the My Sailthru interface on the API and Postbacks page under Settings > Setup.

Sailthru.SPM.setup(customerId, {optionalConfigObject});

Required Parameter

Type

Default

Description

customerId

String

Customer ID, for example b682bb3746796686c27164ba015c3da7.

Optional keys for optionalConfigObject, a JSON object containing key-value pairs:

Optional Key

Type

Default

Description

autoTrackPageView

Bool

true

Specify whether pageviews should be tracked automatically or manually.

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

addSection function

Include an addSection call for each and every section on the page to assign each section an HTML element ID. For HTML-templated sections, Sailthru will render the HTML code to that page element. For JSON sections, the recommendation data is provided via JS and the specified HTML element ID is used only for click-tracking purposes.

Sailthru.SPM.addSection(sectionId, {optionalConfigObject});

Required Parameter

Type

Default

Description

sectionId

String

The ID for the section as it appears in its URL within the SPM admin interface and/or via the SPM API.

Optional keys for optionalConfigObject, a JSON object containing key-value pairs:

Optional Key

Type

Default

Description

elementId

String

The ID of the HTML tag you plan to target with a SPM section. This item is required for all HTML blocks and JSON blocks that are being tracked automatically.

autoTrackImpressions

Bool

true

If true (or unspecified) automatically track impressions. If false, manually track impressions by calling SPM.trackImpressions. (Useful for single-page views, infinite scroll, etc.)

autoTrackClicks

Bool

true

If true (or unspecified) automatically track clicks. If false, manually track clicks by calling SPM.trackClick. (Useful for single-page views, infinite scroll, etc.)

onSuccess

Function

If you’re utilizing the JSON option for the section, the onSuccess function returns parsed JSON content once the personalize function is run successfully.

Adding an onSuccess callback on the addSection function is the Sailthru-preferred approach to returning JSON recommendations. The alternative option for returning JSON recommendations is adding an onSuccess callback on the personalize() function, which returns unparsed raw JSON for all sections on the page.

onError

Function

This function is a success function that is triggered after personalize is run unsuccessfully.

trackPageview function

If you have set autoTrackPageViews to false, you can manually log a pageview using the SPM.trackPageView function at any time, per the following example:

spm.trackPageView(url, {
tags: 'trixie, kong',
onSuccess : function() {console.log('trackPageView success note');},
onError : function() {console.log('trackPageView failure note');}}
});

trackImpression function

If you have set autoTrackImpressions to false, you can log a section impression manually using the this function at any time, per the following example:

spm.trackImpressions(sectionJSONId, "http://example.com/123456",
{
onSuccess : function() {console.log('trackImpression success note');},
onError : function() {console.log('trackImpression failure note');}}
});

trackClick function

If you have set autoTrackClicks to false, you can log a click manually using this function at any time, per the following example:

spm.trackClick(sectionJSONId, "http://example.com/123456",
{
onSuccess : function() {console.log('trackClick success note');},
onError : function() {console.log('trackClick failure note');}}
});

personalize function

Required. The personalize call returns/renders section content and allows you to pass optional parameters.

Sailthru.SPM.personalize({optionalConfigObject});

Optional keys for optionalConfigObject, a JSON object containing key-value pairs:

Field

Type

Default

Description

onSuccess

Function

Whereas onSuccess in the addSection function will return parsed JSON for that section, this instance of onSuccess will return unparsed/raw JSON for all sections on the page if the personalize function is successful.

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.

onTimeout

Function

The function called when the section is not rendered within the timeout period.

timeout

Integer

5000
(ms)

Time in milliseconds before Site Personalization Manager will call the onTimeout 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 passed to the template. (See ”vars object,” below.)

  • vars object
    • If, on page load, you want to send tags to use for filtering the content that will populate the section, your vars array should contain:
      • The array of tags. Your custom key (e.g. mytags) will be made available to your template as a variable containing the tags array.
        {mytags : [array of filter tags]}
      • A boolean value: true to require the tags in the content, orfalse to exclude matching content. Your custom key (e.g. myinclude) will be made available to your template as a variable containing this value.
        {myinclude : [true or false]}
      • In your template, use these two key names as variables passed into the horizon_select function. See “Optional Parameters” on the horizon_select page.
    • You can also include any other custom data that you want to send to the template, making it available for use by your Zephyr code. For example, the value in the pair {mycustomdata : 100} can be referenced in your template using the var mycustomdata.

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

According to the instructions above, you can customize and include the following sample JavaScript code for Instrumented Mode.

<!-- Personalize JS include; Instrumented Mode enabled via data-sailthru-setup attribute -->

   <script src="//ak.sail-horizon.com/onsite/personalize.v0.0.4.min.js" type="text/javascript" data-sailthru-setup="true"></script>


<!-- Functions for Instrumented Mode -->

   <script type="text/javascript">


// setup call. Replace 123456789 with your customer ID
// autoTrackPageView and useStoredTags values default to true, if not included.

   Sailthru.SPM.setup(123456789, {autoTrackPageView:false, useStoredTags:false});


// addSection call. Include a call for each section on the page to associate a
// unique HTML element ID with that section. For HTML-templated sections, Sailthru
// will render the HTML code to that page element based on the specified element ID.
// For JSON sections,the recommendation data is provided via JS; the element ID is
// used only for click tracking purposes. Replace ABC with your HTML element ID.
// autoTrackImpressions and autoTrackClicks default to true, if not included.

   Sailthru.SPM.addSection(section_id,
   {elementId : "ABC",
    autoTrackImpressions : false, autoTrackClicks : false,
    onSuccess : function() {console.log(addSection success note');},
    onError : function() {console.log('addSection failure note');}}
   });


// trackImpressions call. Utilized only if autoTrackImpressions is false in addSection().

   Sailthru.SPM.trackImpressions(sectionJSONId, "http://example.com/123456",
   {
    onSuccess : function() {console.log('trackImpression success note');},
    onError : function() {console.log('trackImpression failure note');}}
   });


// trackPageView call. Utilized only if autoTrackPageView is false in setup().

   Sailthru.SPM.trackPageView(url,
   {
    tags: 'trixie, kong',
    onSuccess : function() {console.log('trackPageView success note');},
    onError : function() {console.log('trackPageView failure note');}}
   });


// personalize call. Pass optional JSON data to the template along with additional
// options; otherwise an empty array. Do not include this function if the page
// does not contain a section.
  
   Sailthru.SPM.personalize(
   {
    vars: {mytags: ["kids", "books", "UK"], myinclude: true, myCustomData: 100},
    timeout : 2000,
    onSuccess : function(data){console.log('Success', data);},
    onError : function(errResp) {console.log('Printing out error', errResp);},
    onTimeout : function() {console.log('Timeout');}
   });
   
</script>
5For 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