Personalize API

Last updated
Save as PDF

Description

recs.richrelevance.com/rrserver/api/personalize

Returns content for the given user and placement.

Parameters

Note: All parameters are case sensitive.

Important: Only call parameters that you need. Omnichannel Personalization operates off a set of APIs that support many applications and clients concurrently. Omnichannel Personalization may update and enhance these APIs at any time.

Name	Required or Optional	Description
apiClientKey	Required	A unique key specific to each API implementation. It identifies the specific application or client for reporting, permissions, and merchandising. This is provided by RichRelevance. Example: apiClientKey=b0126f995ac848159d
apiKey	Required	A unique key that identifies the site. Each RichRelevance client has a unique API key to separate data and traffic from other clients. This is provided by RichRelevance. Example: apiKey=4faeaf752ee40a0f
atcid	Required on Add to Cart page	Add to Cart ID. This can be a single product ID or a list of product IDs. If more than one product is added to the cart, separate the product IDs by using the pipe "\|" character. Example: atcid=uv2345\|xt1234
bi	Optional	Block content item(s). This can be a single content ID or a list of content IDs. If more than one content ID is specified, separate the content IDs by using the pipe "\|" character. Example: bi=content__1\|content__2
callback	Optional	Name of the JavaScript function that JSON data will be passed to. It must be specified for JSONP. The value of this parameter is used as the name of the js function in the response. Example: callback=products_returned
categoryData	Optional	Omits category data (categoryIds and categories) when set to false. The default is true. Example: categoryData=false
categoryId	Required on category_page	The category ID of the category the merchant wants to investigate. The value must match the external ID provided by the merchant to RichRelevance for the category. Example: categoryId=902312
content_ids	Optional	List of content IDs. The content returned is the intersection between the list of content ids passed in the API call and the content from the selected Campaign. Mulptiple content IDs are separated by the pipe "\|" character. Example: content_ids=content__13055\|13056 Note: The provided contentId's should be external Ids.
cv	Optional	Cart value. Used for targeted campaigns involving cart value. It's expressed in cents; for example, $10 is represented as 1000. Example: cv=9550 (this would equal $95.50)
excludeHtml	Optional	True/false. If true, it omits the HTML returned in the RichRelevance server response. If false, the response includes the HTML for the placement which is set in the layout of the html field. The default is false. Example: excludeHtml=true
fpb	Optional	The brand featured on the page. Used to set the seed for brand-seeded strategies, such as Brand Top Sellers. Example: fpb=Microsoft
ipor	Optional	Shopper IP address. Only use if the API request is not coming from the shopper’s device (for example, server-side integration). Example: ipor=255.255.255.255
includeRcs	Optional	True/false. The default is false. If true, it includes rcs string. Example: includeRcs=true
includeScore	Optional	True/false. The default is false. If true, the response will include the score of the selected content for each placement. Example: includeScore=true
placements	Required	List of placement identifiers. Each identifier consists of a page type and a placement name. The identifiers are separated by the pipe "\|" character. You'll receive one piece of content per placement. All placements in a call must be for the same page type. Example: placements=item_page.horizontal\|item_page.vertical
pref	Optional	Shopper’s referrer prior to viewing the page. Used for reporting and merchandising. This is highly recommended. Example: pref=http://www.google.com
productId	Required on item_page, add_to_cart_page, purchase_complete_page, and cart_page (when not empty)	A single product ID, or a list of product IDs. Part of an order definition on the purchase complete page. Use the pipe "\|" character to separate the product IDs. Example: productId=uv2345\|xt1234
rcs	Optional	First party cookie string. This is a encrypted value of Personalization Cloud cookies. It should be passed as it was received in the earlier api response.
recentlyPurchased	Optional	Products the shopper has purchased in the current session. This can be a single product ID or list of product IDs. Products listed here will be considered along with historical data from the RichRelevance system. Use the pipe "\|" character to separate the product IDs. Example: recentlyPurchased=uv2345\|xt1234
rid	Optional	Region ID. Must be consistent with the ID used in the Engage Content Feed. Example: rid=Switzerland-France
sessionId	Optional	Identifies a single visit by a shopper. Sessions are used by behavioral models (to scope user behaviour in a shopping session) and reporting metrics. Example: sessionId=93484
sgs	Optional	Supply user segments. Used for segment-targeted campaigns. List each segment using the format segment_number:segment_name, and then use the pipe "\|" character to separate segments. You must pass both the segment ID and a segment name for each segment. Example: sgs=101:NewUser\|202:Male
ssl	Optional	When set to true, returns http/https depending on how the variable is named in the layout. ssl=true
tagFilter	Optional	Filter contents that match a list of tags. Multiple tags can be passed using the pipe "\|" as a separator. When multiple tags are passed, the returned content should have all tags (it uses AND logic). Example: tagFilter=shoes\|women
tagRefinement	Optional	Refine contents based on a list of tags. The tags in this list will be applied as a filter if there are matching contents available. But if there are no matching contents, then these tags will not be applied as filters. Multiple tags can be passed using the pipe "\|" as a separator. Example: tagFilter=shoes\|women&tagRefinement=Nike Note: tagRefinement will only be applied if tagFilter is being used.
userAttribute	Optional	Custom keys and values that describe the current shopper. Separate information using a semicolon and the pipe "\|" character. Example: userAttribute=eye_color:blue;green\|hair_color:brown
userAttributeReplace	Optional	Usage is same as userAttribute, except that the attributes sent along with userAttributeReplace will replace all previously sent values for that attribute. Example: userAttributeReplace=eye_color:black In the above example all previous values of eye_color will be removed and replaced with black. If the same attribute is sent along in a single request in userAttribute as well as userAttributeReplace, then the value sent in userAttributeReplace will take precedence. This attribute also supports Delete update against attribute values. Example: userAttribute=eye_color:\|hair_color:
userId	Optional	User ID. A unique string to identify each shopper (user). All shopper behavior is stored using this key. It is case-sensitive, and should be the same user ID sent to RichRelevance in other applications. Example: userId=0982347 If no userID is given, recommendations are based on view and purchase history (via the recentlyViewed and recentlyPurchased parameters or cookies) as well as unpersonalized strategies such as CategoryBestSellers.

Example Request

http://recs.richrelevance.com/rrserver/api/personalize?apiKey=ABCD&apiClientKey=1234&sessionId=sess456&userId=u789&placements=home_page.page_area1

Example Response

{
    request: {
        apiKey: "abcd09875",
        clientKey: "f54ea54cb24",
        placements: [
            "home_page.promotion_top_01",
            "home_page.promotion_top_02",
            "home_page.promotion_top_03"
        ],
        sessionId: "null",
        userId: "null"
    },
    rcs: "eF4Ny7ERgDAMA8AmFbuIQ1gO8QbMEZOCgg6YH77_Up7cxaV1DkPPcMhMUGdFrh6xDY8c63S993nM0QJ0mazWZhTxD_ADc7cRDQ",
    placements: [
        {
            creatives: [
                {
                    DESTINATION_URL: "http://recs.richrelevance.com/rrserver/click?a=c6db6e5a99c90d0e&vg=a209885c-4513-4418-0713-f959d6ff5c41&pti=9&pa=promotion_top_01&hpi=11963&rti=2&sgs=&mvtId=-1&mvtTs=1543436683141&uguid=4108b1e3-bc95-4334-4b16-c25997e59ce2&channelId=15937f54ea54cb24&s=&pg=-1&p=content__868&ct=https%3A%2F%2Fwww.verkkokauppa.com%2Ffi%2Fjoulu",
                    START_TIME: "00:00",
                    END_TIME: "00:00",
                    MEDIA_URL: "https://cdn-a.verkkokauppa.com/files/5be3f/39b38/92800/e3f11/d78e.png",
                    trackingUrl: "N/A",
                    SIZE: "six-by-one",
                    campaign: "Joululahjaideat 2018 6x1",
                    ALT_TEXT: "Joululahjaideat. Tilaa kätevästi netistä",
                    R_RECOMMEND: "true"
                }
            ],
            html: "",
            placement: "home_page.promotion_top_01"
        }
    ],
    message: "",
    status: "ok"
}

Field	Description
placements	List of placements with promotions based on the request. This is an array of JSON objects, each describing a single placement..
creatives	A list of the creatives to be displayed. In most cases, this will only be one. Destination URL will be converted for clickTracking purposes and will redirect to the original click through URL
html	Fully formed HTML for the placement based on the layout and selected campaign. It is included in the response by default. Turn off by using the excludeHtml request parameter.
status	A list of the creatives to be displayed. In most cases, this will only be one.
errormessage	Either ‘ok’ or ‘error’.
request	The parameters from the request that Personalization Cloud used in processing the request. Typically used for testing purposes.