Personalization Engine Setup

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

For more information on Personalization Engine, see the Personalization Engine Overview.

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

1. Embed Engage by Sailthru’s JavaScript tag on your pages.
   
   Copy

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

2. In your Settings, enter your site domain(s) and tell Engage by Sailthru 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.

1. Customize and Embed theEngage by Sailthru  JavaScript tag
2. Implement Meta Tags and/or the Content API
3. Set Content Spidering Preferences
4. Understand and Use Engage by SailthruCookies

The configuration steps covered on this page: Note:

• If you are also configuring Engage by Sailthru’s Site Personalization Manager to customize onsite content, you should follow the SPM Implementation steps instead of the instructions below.
• Additional functions available in Engage by Sailthru’s 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 Engage by Sailthru 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 Engage by Sailthru JavaScript V1. An archived copy of our V0.0.4 instructions is available here.

1Customize and Embed the Engage by Sailthru JavaScript

• For default behaviors, simply include the following script and replace <yourID> with your Engage by Sailthru Customer ID:
  
  Copy

  <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 Engage by SailthruContent 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 Engage by Sailthru JavaScript code embedded on your site, replace it with the latest version of the Engage by Sailthru 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 Engage by Sailthru Customer ID which can be found in the My Sailthru interface on the API and Postbacks page under Settings > Setup.

Keys for Optional Configuration Object Parameter

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>

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. Parameters for trackPageView:

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

• 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 Engage by Sailthru-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 Engage by Sailthru tags. However, we recommend that interest tags are Engage by Sailthru -specific (i.e. that “sailthru.tags” is used) for optimum performance.
• Additional supported Engage by Sailthru meta tags exist, beyond these examples. For details and best practices, see Personalization Engine Meta Tags.
• To start using Engage by Sailthru without suitable meta keywords or sailthru.tags, consider Engage by Sailthru’s Auto-Tagging feature.

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 Engage by Sailthru’s spider to automatically add your content pages and their metadata to your Engage by Sailthru Content Library.

Clients with advanced content needs can alternatively add content/attributes exclusively using Engage by Sailthru’s 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 Engage by Sailthru 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: “Engage by 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):
    Copy

    <?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 Marigold’s Support Team.

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

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 Anonymous 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 from Engage by Sailthru 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 Engage by Sailthru’s Site Personalization Manager.
• sailthru_visitor – Cookie for session tracking when using SPM.
  • The cookie contains an id that is used to identify a user’s pageviews within a session.