Skip to main content

​
Server-side

Unlike the client-side method, requests to PureClarity are made on the server, rather than the client’s browser. This requires the PureClarity API to be called directly from your server-side code. Choose the appropriate endpoint based on where your store was created.

​
API Base URL

EU Region: https://api-eu-w-1.pureclarity.net/api/serverside US Region: https://api-us-e-1.pureclarity.net/api/serverside

​
Endpoint

​
POST /api/serverside

Send tracking data and request personalised content

​
Request Schema

​
appId
string
required
Your store views unique access key. This can be found in the PureClarity Admin consoleExample: testAppId
​
secretKey
string
required
The secret key provided for all store view level calls. This can be found in the PureClarity Admin console. Remember never to disclose your SecretKeyExample: testSecretKey
​
currentUrl
string
required
The page url that the user is currently on.Example: http://www.yoursite.com/shop/product/abc123
​
userAgent
string
required
The users browser User Agent string, in all request headers sent by their browser.Example: Mozilla/5.0 (compatible; Googlebot/2.1; +http://www.google.com/bot.html)
​
ip
string
required
The users IP addressExample: 208.67.222.222
​
visitorId
string
The user’s unique PureClarity Visitor ID. This is stored as a browser cookie and set by PureClarity. Discussed in the Cookies documentationExample: testVisitorId
​
sessionId
string
The user’s unique PureClarity Session ID, that represents their current visit. This is set by PureClarity and is stored as a browser cookie. Discussed in the Cookies documentationExample: testSessionId
​
referer
string
The referer value from the users browser header. This is the page that the user has come from, not this current pageExample: http://www.yoursite.com/shop/
​
currency
string
Set’s the currency of the products to be returned. The value should be a valid ISO currency code. If not present the default currency configured in PureClarity will be used. Only products that have been sent to PureClarity with this currency price will be returnedExample: USD
​
events
array
An array of tracking event objectsEach event object contains:
  • name (string, required): The identifier of the track event (e.g., product_view)
  • data (object): The contextual data that accompanies the tracking event. Format determined by the event type (e.g., {"id": "abc123"})

​
Response Schema

​
visitorId
string
The user’s unique PureClarity visitor ID. This should be set as the pc_v_<access_key> cookie in the users browser. The expiry of the pc_v_<access_key> cookie should be set to unlimitedExample: testVisitorId
​
sessionId
string
The user’s unique PureClarity session ID for the current visit. This should be set as the pc_sessid_<access_key> cookie in the users browser. The expiry of the pc_sessid_<access_key> cookie should be set to 5 minutesExample: testSessionId
​
errors
array
Contains each error that occurred should there be any issuesArray of string error messages
​
zones
object
An object that contains the result for each zone on the requested page. Each key property name, with an object that represents the zone content dataExample: {"HP01": {"type": "staticimage"}}

​
Example Request

{
  "appId": "testAppId",
  "secretKey": "testSecretKey",
  "currentUrl": "http://www.yoursite.com/shop/product/abc123",
  "userAgent": "Mozilla/5.0 (compatible; Googlebot/2.1; +http://www.google.com/bot.html)",
  "ip": "208.67.222.222",
  "visitorId": "testVisitorId",
  "sessionId": "testSessionId",
  "referer": "http://www.yoursite.com/shop/",
  "currency": "USD",
  "events": [
    {
      "name": "page_view",
      "data": {
        "page_type": "product"
      }
    },
    {
      "name": "product_view",
      "data": {
        "id": "abc123"
      }
    }
  ]
}

​
Example Response

{
  "visitorId": "testVisitorId",
  "sessionId": "testSessionId",
  "errors": [],
  "zones": {
    "HP01": {
      "type": "staticimage",
      "content": {
        "imageUrl": "https://example.com/banner.jpg",
        "linkUrl": "https://example.com/promotion"
      }
    },
    "PDP01": {
      "type": "recommender",
      "products": [
        {
          "id": "prod123",
          "title": "Related Product",
          "price": 29.99
        }
      ]
    }
  }
}

​
Usage

Use the server-side endpoint, and pass the appropriate tracking events based on what page the user is currently on. If you detect the user has updated their basket, send the set_basket event. If the user is on a product page, send the product_view event. If the user has logged in, send the customer_details event. You can send multiple events in each request. Ensure you always send the page_view tracking event, and set the page_type context. This ensures that the response from PureClarity will contain information about the personalised content to show.
Please read our Implementation Methods guide to determine whether to use client-side or server-side for your site.
We recommend you use our client-side implementation unless they have a specific requirement for using our server-side API.