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, add_to_cart_page, purchase_complete_page, and cart_page (when not empty) |
|
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 | |
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. 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 | |
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. |