Loading...
Area: Episerver Product Recommendations
Applies to versions: 1.4 and higher (Server-to-Server API)
Other versions:

Common elements

Recommended reading 

The following fields are common to all request types.

Name Description and usage
type Type of request.

Determines the format of the message. It should be one of the following:
ip [Optional]

IP address of the site visitor

If specified, you can use the IP address for a geolocation lookup to identify the approximate location of the visitor for a personalized online experience for Promote. The IP address is not stored.
session ID of the Episerver session established with the tracker.

Use new if no session was established with Episerver yet.

Returns the allocated session on a successful response. Use that session ID for subsequent requests for this cuid and session.

Sessions should expire after a period of user inactivity (such as four hours), so any requests after this period should revert to new.
cuid Consolidated user ID.

Use new if the cuid is unknown.

Returns the cuid value on a successful response. Store the cuid in persistent storage and send it back in future requests so you can track the same customer across multiple sessions (see Storing customer IDs).

Note: Use the same cuid for subsequent requests related to the same user/device.
site Site code of the Episerver customer.

Identifies the retailer's site with the site code provided by Episerver.
clientToken Authentication token for the Episerver customer; a token provided to the Episerver customer that must be included as part of the JSON data in every API call.

A separate clientToken is issued for each channel.

Ensure that you are using the correct token for your channel.

Note: Any clientToken provided by Episerver to access the RESTful service hosted on Episerver's UAT server is different from the one provided for the service on Episerver's live server. Make sure you are using the appropriate clientToken.
channel [Optional]

Access channel. It should be one of the following:

  • web
  • mobileweb
  • mobileapp
  • tv
  • callcenter
  • facebook
If omitted, web is assumed.

Contact Episerver if you need more channels. A separate clientToken is issued for each channel. Ensure that you are using the correct token for your channel.
lang Language code.

See Language codes.
currentURI Site visitor's current URI.

For example, for web customers, this is the current URI (uniform resource identifier).
previousURI Previous URI of the site visitor before the current one.

For example, for web customers, this is the referrer header.
user [Optional]

For example: 
"user" : {…}

Note: When you provide user, also supply id. Use id instead because name and email are deprecated and kept for backward compatibility.

  • email
    [Deprecated] [Optional]
    The email address of the customer. For example: 
    "name"  : "John Customer",
"email" : "john.customer@email.com"
  • id
    [Optional]
    Pseudonymised ID of the user. For example: 
    "id" : "abcd1234efgh"
    This identifies the user in the Personalization system. Use the user ID to improve tracking and recommendations; you can use it also in other Episerver products, such as Mail and Triggers.

    Note: For Product Recommendations, to prevent user behavior from being lost, you need to send Episerver an up-to-date mapping between email addresses and pseudonymized user IDs. This needs to be provided only once so that Episerver Personalization can replace existing customer email addresses with their corresponding pseudonymized user ID.
userAgent User-Agent string

Information about the site visitor’s browser and operating system.

Mandatory from v1.3 of the Server-to-Server API.
abTestContent [Optional]

Controls how much A/B test information to return in the response data.

Available values are:
  • summary Only the test name and A/B group are returned in the response.
  • full All available A/B group information is returned in the response.
If this attribute is omitted, no A/B Testing information is returned.

See A/B testing for more information.
recContent [Optional]

Recommendation content configuration for Recommendations.

Available values:
  • full Returns full product details (such as, price, image, title, URL). This is the default behavior if recContent property is omitted.
  • refCodeOnly Returns a list of elements containing only product reference codes and recommendation IDs.
smartProducts [Optional]

Only applicable if you are using multiple Episerver products on a page. It overrides the configuration for a page, letting you switch off the generation of Episerver products for this request.

If smartProducts is not defined, the content for all Episerver products defined for the page is returned as normal.

An array of strings listing the Episerver products to include in the response for this page. Available values are smartRecs for Recommendations and smartContent for Promote.

For example, if Recommendations and Promote are configured for a page, but you only want results returned for Promote and not Recommendations, then include the smartProducts property in the request as follows: 
smartProducts : [ “smartContent” ]
To return no Episerver product information on a page, use smartProducts as follows: 
smartProducts : []
info [Optional]

Variable metadata information about clicks, A/B test information, and so on. See Click tracking and A/B testing.
customAttributes [Optional]

Allows real-time filtering of recommendations based on the specified custom attributes.

A comma-separated list of attribute names and values. Attribute names must contain no spaces. 
"customAttributes" : { 
                       "customerType" : "XL",
                       "userLocale"   : "en_GB", 
                       "userSegment"  : "gold"
                      }
Custom attributes are used only in real-time; they are not stored in the system.
customer [Optional]

Used for B2B customers, customer is an all-encompassing object in the tracking model that contains information based on a client's customer.
  • You can optionally ensure that your object in the tracking message is populated correctly, stating the customerId and segmentIds so the customer can view in your system.
  • Set the feed up to associate the products with the segmentIds that are associated to the product.
  • When you provide this data, filter recommendations later in the process and show only recommended products from a user's segment.
  • You can additionally filter using the marketsegment expression. For example: u.marketsegment = "roofing"
    • u.marketsegment. Matches all market segments of the current session from tracking.
    • r.marketsegment. Matches all market segments for the recommended product from the catalog.
    • p.marketsegment. Matches all market segments of currently viewed product (segments from the catalog).
As of version 1.4, a new field in the tracking request allows for the handling of your customers in the tracking request, as shown in the following code. 
{
  "customer" : {
                 "customerId" : "someCustomerId",
                 "segmentIds" : [
                                  "someSegmentId",
                                  "someOtherSegmentId"
                                ]
               }
}
  • customerID Identifies your customer. (Must be unique.)
  • segmentIDs A list of segmentIds to which your customer belongs. Map these identifiers according to how you deal with data segregation. This field maps to the segmentId's associated with products in the feed configuration. Segments in this list allow for optional filtering against the product segment ids.
Do you find this information helpful? Please log in to provide feedback.

Last updated: Nov 06, 2017

Recommended reading