Site Recommendations Implementation

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 Sectionconfigure-section.html

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 Engage by 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.

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>

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.

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>

For examples of the use of these parameters, see Example JavaScript Configurations.

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.

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.

• 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. This data is used to personalize the display for unknown 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 Unknown User Conversion.)

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');}
}); 

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);}
});

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);
   }
});

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

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>

Custom Mode: Include Custom Callback Functions for User-Signup Overlay Response

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

Custom Mode: Retrieving a User's Email Address after Conversion Using onSignupSuccess

<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 Engage by 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"    }
}