personalize

The personalize() function is the cornerstone of each personalized template, whether used in email or Site Personalization Manager. Based on your chosen Sailthru recommendation algorithm and additional configuration options, personalize() returns an array of the best-matching content or products for the user whose template is currently being rendered.

list personalize( object data )

The data JSON object contains all configuration parameters, which are described in the Parameters table below.

Example Configurations

  • Use the context algorithm
    • Return the top 5 (default quantity) items most-commonly bought by users who bought the item at the current/specified URL
  • Include only items with tags boots and child
  • Exclude items with tag black
{resultArray = personalize({
  "algorithm" : "context",
  "context_key_type" : "url",
  "context_key" : "http://example.com/item.html",
  "include_tags_all" : [ "boots", "child" ],
  "exclude_tags_any" : [ "black" ]
})}
  • Use the interest algorithm
    • Return the top 20 items from the current feed that have interest tags best matching the known interests of the current user
  • Include only items with tags boots and child
{resultArray = personalize({
    "algorithm" : "interest",
    "size": 20,
    "include_tags_all" : [ "boots", "child" ]
})}

personalize is a replacement for the horizon_select function, which offers only one recommendation algorithm, accessible to personalize by setting the algorithm to interest.

Available Algorithms

personalize offers a choice of the following algorithms, all of which return the best-matching content items for a given user based on their criteria listed below. For all algorithms except interest, the content is sourced directly from your Sailthru Content Library, unless you provide a specific feed to use as an alternative. Results are returned in ranked order starting with the strongest match.

Algorithm Name

Description

Method Type

Popular

The most popular items from across your Content Library based on purchases in the recent past. If your account does not contain purchase data, the most-viewed items are used.

Ranking

Trending

The items that have gained in popularity in the past week, based on their number of purchases. (Commerce sites only.)

Context

Coming Soon

Based on a provided content item, considering the history of other customers who viewed or purchased that item, finds the other items they also viewed/purchased.

Does not leverage specific user data for recommendation purposes, so is appropriate for anonymous users.

Collaborative filtering

(Wisdom of the crowd)

Context:
Purchased

Coming Soon

Based on a provided item, considering the history of other customers who purchased that item, finds the other items they most commonly purchased, while also taking into account the unique purchase history of the current user.

Context:
Pageview

Coming Soon

Based on a provided content item, considering the history of other customers who viewed that item, finds the other items they most commonly viewed, while also taking into account the unique page-view history of the current user.

Interest

This selection enables the same algorithm used by the Zephyr function horizon_select() to return items in the feed with tags that match the user’s interest profile. Optional parameters include:

  • heat – Recent highly-viewed items from the feed
  • random – Random item from the feed

Does not use the Content Library. Requires a feed of content. Uses the feed that is assigned to the template or an alternative content array, if specified (e.g. a feed that you have filtered within your Zephyr code).

Interest

(Content-based filtering)

Predictive

Requires Prediction Manager subscription

The products a user is most likely to buy based on machine-learning models that incorporate signals from the user’s interests, collaborative filtering, and engagement activity. (Only available with a Prediction Manager subscription.) Predictions are updated daily, and each day we ingest new user activity to update the machine-learning models as well as the specific product predictions for each user.

Predictive

(Machine learning)

Random

A randomized selection of content, either from a feed or the Content Library.

Random

Recommended Algorithm Usage

Each algorithm commonly performs well on certain types of pages, but it is highly recommended that you test multiple algorithms to determine which works best in your environment. You can also try merging results from multiple algorithms using the Zephyr function content_intersect.

You can use these tables to get started and you are also encouraged to discuss options with your customer success manager.

Commerce

personalize table commerce

personalize table key

Media

personalize table media

personalize table key

Parameters

Parameter

Required/
Optional

Default Value

Description

algorithm

optional

popular

Specify whether to use context, predictive, interest*, trending, popular, or random.
*Requires a feed with tags for each item

size

optional

5

The number of items you wish to return in the resulting content array

content

optional

content

Applies only to the interest algorithm. Default “content” is the content of the feed assigned to the template. Specify an alternative content array if, for example, you transform content within your Zephyr code to create a different source array to pass to personalize().

context_key_type

optional

url

url, sku, title, or content_id.

url or sku are recommended. content_id is only accessible in Sailthru-generated Content Feeds.

context_key

conditionally required

[URL of the current page]

Identifier for the content item being compared to others using the context algorithm.

Required for email templates using the context algorithm or for any templates where context_key_type is specified.

In SPM, by default, the context algorithm will use the URL of the current page as item context, unless you use context_key to specify an alternative URL or context_key + context_key_type to specify any alternative key.

In email, there is no default URL. Usecontext_key to specify a URL, or context_key + context_key_type to specify any other key.

include_tags_any

optional

 

At least one of your specified tags must be present on an item for it to be included in the resulting content array. (I.e., filter by tags using OR logic.) Can be used in conjunction with include_tags_all.

include_tags_all

optional

 

All of your specified tags must be present on an item for it to be included in the resulting content array. (I.e., filter by tags using AND logic.) Can be used in conjunction with include_tags_any.

use_pinning

optional

true

If false, ignore pinned item locations, if any are specified on the feed.

horizon_type

optional

 

If algorithm is set to “interest”, you can replicate the “random” mode of the horizon_select function using the parameter random.

Parameter Usage

Pass any parameters as a JSON object into the personalize() zephyr function.

{
   "algorithm" : <string>,
   "size" : <int>,
   "context_key_type" : <string>, "context_key" : <string>,
   "include_tags_any" : <string>, "include_tags_all" : <string>,
   "use_pinning" : <string>,
   "content" : <array>, "horizon_type" : <string>
}

Notes

  • Line breaks are not supported within Zephyr functions. Do not include line breaks in your object.
  • The ability to specify tags for filtering is especially useful with Site Personalization Manager: based on the context in which the page is being viewed (e.g. a site category/section), you can dynamically pass in variables/tags on page load in order to affect the content that is displayed. Note, however, that tag filtering is also available when creating a content feed for use with the interest algorithm, and can also be done manually in your template’s Zephyr code using filter() andfilter_content().
  • For all algorithms that use your Sailthru Content Library as their source, when an item’s URL changes, that item is considered a new item, and will start over with zero pageviews, purchases, and context. Assuming the URL was the only change, the new item will also be a “duplicate” of the old one until you delete the previous URL from the Content Library.
Top