API (on apiary.io):
- Persoo Admin API – for the account configuration and visitor’s history view
- Persoo RTP API – for getting recommendations and offers, live visitor profiles (full browsing history is available through a unique request)
Apiary has it’s advantages for testing requests. You don’t have to use curl or other tools, if you don’t want to. Just fill your authorization data in Apiary, and you can test live request there.
Examples of RTP API calls
For serving recommendations
the workflow method workflow – reporting visitor’s data and recommendations. This method is used by the browser when rendering recommendations, but can be used directly as well.
|
1 |
https://rtp.persoo.cz/<yourAccountID>/<environment>/workflow.json?requestParameters |
Returns JSON.
- data – event-related data. E.g. IDs of recommended products for each scenario or custom data for each visitor profile requested.
- functionCalls – calling JS functions. Usually in the sense of “render a box in location X with the HTML code Y” or “report a custom variable into Google Analytics”…
- exceptions – exceptions that happened on the server when processing the event and given workflow (it’s possible to define custom variables and functions, which are often the cause of the exception).
- debug – debugging info if the debug mode is on.
Example:
You report a pageview in the request, and get back a list of product IDs for all scenarios for that page.
|
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 |
/<account>/<environment>/workflow.json?... { "data": { "scenarios": { "hpRecommend": { "ids": [ "11564", "12151", "11570", "12198", "12854" ] }, "lastViewed": { "ids": [ "11582", "11569" ] } } }, "exceptions": [], "functionCalls": [] } |
More detailed info on workflows can be found here:
- docs.persoortp.apiary.io/workflows-for-request-processing – serving recommendations and supported workflows
- docs.persoortp.apiary.io/examples
Notes to calling RTP API:
- There are two modes available:
- Either the visitorID is given (that identifies the browser), in which case the request does not have to be authorised,
- Or we work with a specific profile, that needs to be identified with an e-mail, userID etc. In this case, we have to pass an auth token to prove that we have the right to access this data.
- Take note that the RTP requests need a referrer to know who is calling, and for which URL the recommendations are given. It won’t respond without a referrer.
For enriching a lead
The mehod getVisitorDetail
|
1 |
adminapi.persoo.cz/<yourAccountID>/visitors/<idType>/<idValue> |
returns
- Basic Visitor Profile info (basic metrics, IDs, tags…)
- All transactions related to the Visitor
- Browsing history organised into sessions
See example on apiary (bottom right), or:
|
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 |
{ "profile": { "email": "richardT@gmail.com", "lastVisit": 1453367168028, "revenueTotal": 167, "sessionsTotal": 1, "...": "...other data ..." // viewed destinations, viewed hotels, preferences, used filters,... }, "sessions": [ { "browserID": "AAABUcPLB/kZcRzdIXcWPcIF", "timestampFrom": 1450688842422, "timestampTo": 1450688844087, "events": [ // basically everything reported in the page's Data Layer, including dynamic events reported though GTM { "itemID": "10084", "pageType": "detail", "timestamp": 1450688843481, "url": "http://my-eshop.com/productDetail/10084" }, { "basketItems": { "10007": { "quantity": 1 } }, "basketTotal": 123, "pageType": "basket", "timestamp": 1450688843834, "url": "http://my-eshop.com/basket/step1" } ] } ], "transactions": [ { "transactionId": "1444121440001", "timestamp": 1444121443030, "items": { "10084": { "categoryID": "Shoes", "price": 167, "quantity": 1 } }, "total": 167 } ] } |
Note about calling the Admin API:
- We need to authorize through a helper method /login, which sets the cookie for a domain adminapi.persoo.cz, and authorizes all future requests (until the cookie expires – each request refreshes the cookie)