Personalize API
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 | |
apiKey |
Required | |
atcid | Required on Add to Cart page | |
bi | Optional | |
callback |
Optional | |
categoryData |
Optional | |
categoryId | Required on category_page | |
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 | |
excludeHtml |
Optional | |
fpb |
Optional | |
ipor | Optional | |
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 | |
productId |
Required on item_page, purchase_complete_page, and cart_page (when not empty)
|
|
rcs | Optional |
Algonomy Cookie String. This is the encrypted Algonomy cookie for the user associated with the API request. It should be passed exactly as it was received in a prior API response. Clients should ensure to preserve the 'rcs' value just as it was served. The 'rcs' parameter is always alphanumeric and case-sensitive, with the token value including a mix of uppercase letters, lowercase letters, and numbers. Note: The 'rcs' parameter allows merchants to effectively provide the Algonomy platform access to a user's Algonomy browser cookie by acting as a cookie proxy (or cookie pass-through). This process involves the merchant reading and writing a user's Algonomy browser cookie and passing it to and from Algonomy via the server-side API. |
recentlyPurchased |
Optional | |
rid | Optional | |
sessionId |
Optional | |
sgs |
Optional | |
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 using advanced logic such as AND (&&), OR (||), and NOT (!) operators. Note: You need to URL encode the '&&' operator. To encode a URL with the ampersand character, use %26. Multiple tags can be passed using the pipe "|" as a separator. When multiple tags are passed, the returned content should have all tags. Example: tagFilter=(shoes||women)&&Nike Filter of ( Note: You can also group together the logical expressions to combine multiple expressions. |
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 | |
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: userAttribute=eye_color:|hair_color: |
userId |
Optional |
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. |