Personalization Engine Setup

Configuring Personalization Engine and adding the JavaScript tag on your site will enable you to import your site’s content into the system and track your users’ behavior and interests. With this data, you can provide optimal personalized content to your users.

The simplest approach to get up and running requires just two steps:

Embed the JavaScript tag on your pages.

<script src="https://ak.sail-horizon.com/spm/spm.v1.min.js"></script>
<script>Sailthru.init({ customerId: '<yourID>' });</script>

In your Settings, enter your site domain(s) and tell the system which kinds of URLs contain content that should or should not be pulled into your Content Library.

However, there are many additional features to consider that require additional configuration steps, like additional JavaScript functions appended to the above code. Some of these features include:

Setting custom metadata on your content items
Making direct updates to the Content Library via API
Manually tracking onsite user actions or interests via JavaScript

Review the configuration steps below and speak with your Customer Success Manager to determine which methods will work best for you.

The configuration steps covered on this page:

Customize and Embed the JavaScript tag
Implement Meta Tags and/or the Content API
Set Content Spidering Preferences
Understand and Use Cookies

Note:

If you are also configuring Site Recommendations to customize onsite content, you should follow the Implementation steps instead of the instructions below.
Additional functions available in the JavaScript that allow you to record user signups, purchases, and events are not covered on this page. After you implement the JavaScript according to the instructions below, please see the JavaScript API Library documentation to consider or implement these additional functions.
If you would like to use Google Tag Manager to implement this script tag and/or the optional functions, a guide is available here.
These instructions are for JavaScript V1. An archived copy of our V0.0.4 instructions is available here.

1Customize and Embed the JavaScript

For default behaviors, simply include the following script and replace <yourID> with your Customer ID:

<script src="https://ak.sail-horizon.com/spm/spm.v1.min.js"></script>
<script>Sailthru.init({ customerId: '<yourID>' });</script>

You may also include additional parameters to determine whether the page should be spidered and/or whether the stored tags from the Content Library or new custom tags should be used for user-interest attribution. Note that this is a per-page setting, so you can opt to enable different functions/parameters on different types of pages on your site.
If you already have a legacy JavaScript code embedded on your site, replace it with the latest version of the JS.

JavaScript Options
Default Behavior	Configured Behavior
Auto-tracking of pageviews.	Manual tracking option available for pageviews. (Ideal for single-page views, such as infinite scroll, and dynamic single-page sites.) Auto-tracking is the default.
Tags to be recorded as user interests when an item is viewed are those spidered or sent via the Content API and stored for each item in your Content Library.	Tags for viewed items to be recorded as user interests can be manually specified in the JS code, regardless of whether others are stored for the content item in the Content Library.
URL of current page is identified automatically, with query strings included or excluded based on sitewide Spider Preferences.	URL of current page can optionally be explicitly specified in the JS.
Whether to spider page is determined by sitewide Spider Preferences.	Whether to spider page can be determined in the JS.

If you are using default behaviors, you can skip the rest of this section and go directly to section 2, Implement Meta Tags and/or the Content API.

Required Function

init

Sailthru.init({ customerId: '<yourID>', <optionalConfigParameters> });

This function requires your Customer ID which can be found in the My Sailthru interface on the API and Postbacks page under Settings > Setup.

Required Parameter	Type	Default	Description
customerId	String	N/A	Customer ID, for example b682bb3746796686c27164ba015c3da7. Replace customerId with the one displayed for your account in My Sailthru on the Settings page API & Postbacks.

Required Parameter

Type

Default

Description

customerId

String

N/A

Customer ID, for example b682bb3746796686c27164ba015c3da7.

Replace customerId with the one displayed for your account in My Sailthru on the Settings page API & Postbacks.

Keys for Optional Configuration Object Parameter

Optional Key	Type	Default	Description
isCustom	Bool	false	Unless you are using Recommendations, setting isCustom to true does not change your functions’ behavior in itself, but it enables the autoTrackPageview parameter, which you may use to prevent the default automatic tracking of a pageview attributed to the current URL. isCustom enables additional functionality if you are using Site Personalization Manager. (See SPM Implementation.)
autoTrackPageview	Bool	true	Specify whether pageviews should be tracked automatically on page-load, attributed to the current URL. You can track pageviews manually using the trackPageView function, which is useful when a single URL may display an array of content items. (isCustom must be set to true in order for this parameter’s “false” value to take effect.)
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.
excludeContent	Bool	false	Determines whether the system should spider the page on which the Javascript appears. Set this to true to prevent spidering. (Note that when set to true, the page will not be spidered or count pageviews.)

Include any keys as key-value pairs using object-literal syntax. For example:

<script src="https://ak.sail-horizon.com/spm/spm.v1.min.js"></script>
<script> Sailthru.init({ "customerId": "<customerId>", "iscustom": true, "autoTrackPageview": false, "useStoredTags": false, "excludeContent": true }); </script>

The sailthru.init function also takes the onSuccess parameter. For example:

<script src="https://ak.sail-horizon.com/spm/spm.v1.min.js"></script> <script> Sailthru.init({ "customerId": "<customerId>", "iscustom": true, "autoTrackPageview": false, "useStoredTags": false, "excludeContent": true, onSuccess: (results) => {console.log('Got sections!')} }); </script>

Additional Functions for Configured Behaviors

Default behavior is used for each function if it is not included.

track

Optional. Used to manually register pageviews. This is Ideal for single-page views, such as infinite scroll, and other dynamic single-page sites. You can log a pageview using the Sailthru.track function at any time. This is typically used when autoTrackPageview is set to false. Note that if you leave autoTrackPageview set to true and use Sailthru.track multiple pageviews will be logged.

Sailthru.track('pageview', { 
   url: <url>, 
   tags: <tags>, 
   onSuccess : function() {console.log('trackPageView success note');}, 
   onError : function() {console.log('trackPageView failure note');}
});

Parameters for trackPageView:

Required: Replace url with a variable representing the URL for which you want to track a pageview.
Required: JSON object parameter containing key-value pairs. (May be empty if no optional keys are included.)
- Optional: If you wish to attribute a custom array of interest tags to the user who views this page, rather than those which may be stored for the associated URL in the Content Library, replace tagsVar with your tags: either a string of comma-separated tags or an array of strings, one for each tag.
- Optional: Include onSuccess or onError callbacks.

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

<script src="https://ak.sail-horizon.com/spm/spm.v1.min.js"></script>
<script type="text/javascript">

Sailthru.init({ customerId: '<customerId>' , isCustom: true,
autoTrackPageview: false, useStoredTags: false });

Sailthru.track('pageview', { 
   url: <url>, 
   tags: <tags>, 
   onSuccess : function() {console.log('trackPageView success note');}, 
   onError : function() {console.log('trackPageView failure note');}
});

</script>

2Implement Meta Tags and/or the Content API

Personalization Engine crawls pages that are found by our Spider or submitted using the Content API. Similar to search bots, the Spider records meta tags to determine the key attributes of each item-specific page, including interest tags, though you can also submit content metadata using the Content API.

Personalization Engine also measures content popularity by pageviews, which can further weight content in Personalization Engine-powered products. For a full list of algorithms that you can use to determine which items are displayed to users, see the Zephyr function personalize().

You can add system-specific meta tags to the content pages of your site. The text in “sailthru.tags” should correspond broadly to the interests of users. For example:

<meta name="sailthru.date" content="Tue, 05 Apr 2012 23:26:57 -0400" />
<meta name="sailthru.title" content="Belichick named top coach in the NFL" />
<meta name="sailthru.tags" content="sports, football, nfl, new-england-patriots" />

If you already have a meta “date” tag or suitable tags as meta “keywords”, you do not need to provide those as custom tags. However, we recommend that interest tags are system-specific (i.e. that “sailthru.tags” is used) for optimum performance.
Additional supported meta tags exist, beyond these examples. For details and best practices, see Personalization Engine Meta Tags.

For more information on using the Content API to submit page metadata or request spidering of pages, see the Content API page.

3Set Content Spidering Preferences

You can leverage the system’s spider functionality to automatically add your content pages and their metadata to your Content Library.

Clients with advanced content needs can alternatively add content/attributes exclusively using the Content API, or use a hybrid approach with both features: for example, spider content, then use the API to add additional metadata, update content, delete outdated content, or request a respider.

If you intend to spider any content:

Specify which URLs and URL structures to allow the system to crawl in Spider Preferences. For example, you can choose to “include” your entire domain, but “exclude” category and landing pages.
- Note: An alternative way to exclude pages is through the JavaScript on each page using the “excludeContent” parameter. To exclusively use the JS on each page to determine whether the page is spidered, leave “Include Rules” blank. If you simply want to exclude pages using JS, you can add “Include Rules” and use the JS to exclude pages from that set of matching URLs.
To learn more about setting up these rules, see Personalization Engine Setup: Include/Exclude Pages.
Note that query strings appended to URLs (for example, example.com/?queryparameter=queryvalue) are ignored by the spider. If you would like certain query parameters and values to be included as part of the stored URL in the Content Library, add those parameter names on the Spider Preferences page. Enter them in the “Spiderable Query Params” section, one per line.
The first time a spiderable page is loaded, its metadata is added to the Content Library.
If your site is login-only
- Click for instructions on how to let the spider in automatically
  The Spider passes an HTTP User-Agent header that is unique to your account. Follow the steps below to obtain your unique Spider User-Agent name, and then allow the agent access to your site.
  1. Login to my.sailthru, and go to your Settings page.
  2. Click the lock icon under the heading API Key and Secrets at the top left of the page.
  3. Copy the text from the Spider User-Agent section. For example: “Sailthru Content Spider [Account Name/abcefgh12345]”
  4. On your login website, you will typically check if a user is logged in and if not, redirect them to the login page. To this existing code, you just need to add a check of the SERVER/USER AGENT. This check uses the Content Spider key. The website recognizes the key, and allows the Horizon spider to login to gather user interests/clicks.
  For example (in PHP):
```
<?php
 . . .
 //ensure user is logged in
 if (!isset($_SESSION['user']) && $_SERVER["HTTP_USER_AGENT"]=="Sailthru Content Spider [Sailthru Client Name/12334567832481348asfasdf]") {
 redirect("login_page");
 }
 . . . web page desired to be spidered . . .
```
  If you are having difficulty editing your site to allow our spider access or are unsure of the best way to go about doing this, please contact the Support Team by selecting the blue button at the bottom of the page.

If you intend to manage content exclusively using the Content API, with no spidering:

Do not enter any “Include Rules” on the Spider Preferences page.

Note: If the web server your site is hosted on is forcing GZIP compression, the pages cannot be spidered. In this case, please use the Content API instead.

4Understand and Use Cookies

As users interact with your site and email, browser cookies are dropped to track their activity and identify known users.

The following cookies are dropped automatically by the Personalize JavaScript, as needed. The only configuration steps you may require would pertain to the described API integrations. For information on manually setting a cookie, see the User API documentation.

sailthru_content – Tracks recent pageviews for all visitors, and can be used to populate a new user profile. Note: It is highly recommended that you configure your site to submit this cookie value through the User API on each user signup. See Unknown User Conversion.
sailthru_hid – Uniquely identifies known users in order to track their onsite activity. It is dropped under the following scenarios:
- Signup – When a new user signs up on your site.
- Site Login – When an existing user logs in, if the cookie was not already present.
- Email Click – When an uncookied user clicks through an email and visits your site.
- Purchase – When a user makes a purchase on your site and the email address does not yet belong to a known user. (Commerce sites only. Requires Purchase API integration.)
sailthru_bid – Set when a subscriber opens and clicks an email link, to attribute onsite actions to a particular email campaign. (Note that this requires that you have set up a CNAME for link rewriting and have added this to the Link Domain setting in your account.) Commerce clients should pass this cookie as message_id when making any purchase API call.
sailthru_pc – Tracks SPM clicks. This only applies if you have implemented Recommendations.