Skip to main content
RichRelevance

How to Use Social Proof Experience Output API - Category/List Pages

How to Use Social Proof Experience Output API - Category/List Pages

Social Proof APIs help to display dynamic social proof messages, the details about how to use these APIs are described in the following sections.

How to obtain API Key

  1. Log in to Omnichannel Personalization.
  2. On the Omnichannel Personalization Dashboard page, on the left navigation rail, click the customer site name dropdown list and then select the required client name.
  3. Click  available next to the customer site name dropdown list. The Site-info window is displayed.

  4. From the Site-info window, copy the API Key and save it to your drive.

Request Call

GET method is used to get the responses.

GET /rrserver/api/engage/spMessages?apiClientKey={apiClientKey}&apiKey={apiKey}&sessionId={sessionId}&placements=list_page&p={pId1|pId2}&userId={userId}&rcs={remoteCookieStoreValue}

Required Parameters:

  • All target API parameters

  • All experiences API parameters

  • All social proof metrics API parameters (apiKey, apiClientKey, productId)

Request Call Parameters

The following parameters are used in social proof API.

Name Required or Optional Description

apiKey

Required

Valid API key corresponding to a particular site

apiClientKey Required

Valid API client key for a particular site

productId or p Required

Unique ID (external ID) for a product. This should be a key to look up in the catalog.

Note: If the specified Product ID is not present in the Personalization catalog, the system will not accept the request.

Used by

  • Social Proof API

    one or more external productIds separated by pipe delimiter.

  • Targeting API

    For item page, single productId will be there.

    For list/cart/category page, we can provide list of productIds separated by '|' delimiter.

placements Required

This pagetype is selected as a context in social proof experience.

For example: item_page, cart_page, and category_page.

sessionId or s Required

Used by all APIs

Identifies a single visit by a customer. Sessions are used by behavioral models (to scope user behavior in a shopping session) and reporting metrics.

Example: sessionId=93484

userId or u

Optional

Used by trackevent API

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.

categoryId

Optional

The category ID of the category the merchant wants to investigate. The value must match the external ID provided by the merchant to Algonomy for the category.

Example: categoryId=902312

rid Optional

Region ID. It must be consistent with the ID used in the product region feed.

Example: rid=Switzerland-France

channelId

Optional

Channel ID is used by some Algonomy reports to differentiate channels such as mobile or desktop.

Example values are WEB, WEB_PHONE, WEB_TABLET. It can be any API client key that an Algonomy consultant has set up for a customer.

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

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

lang

Optional

Identifies the language requested using the language code.

Example: &lang=sv-SE

  • Notes:

    The 'lang' parameter is supported and utilized based on the setup configured for event metrics.

  • For more details on setting up the event metrics, see Event Metric Setup.
  • For more details on 'lang' parameter, see Language Parameter.

Sample Social Proof APIs Request and Response

API Request

https://qa2.richrelevance.com/rrserver/api/engage/spMessages?apiClientKey=xxxxxxxxxxxxxxxx&apiKey=xxxxxxxxxxxxxxxx&s=5oa14nulbga5p2ud3zilg34b18&placements=category_page&categoryId=FOOTWEAR&p=232564|216919|202030

API Response

{
  "dynamicSocialProofMessages": [
    {
      "experienceId": xxxx,
      "variationId": xxxx,
      "locationSelector": "img : data-itemId",
      "displayDuration": 0,
      "displayInformationList": [
        {
          "productId": "xxx_xxx-xxxx-xxxx-xxx",
          "messageList": [
            {
              "count": 4058,
              "finalMessage": "4058 people viewed today",
              "threshold": 1,
              "order": 1,
              "messageText": "@usercount people viewed today"
            }
          ]
        },
        {
          "productId": "xxx_xxx-xxxx-xxxx-xxx",
          "messageList": [
            {
              "count": 16119,
              "finalMessage": "16119 people viewed today",
              "threshold": 1,
              "order": 1,
              "messageText": "@usercount people viewed today"
            }
          ]
        },
        {
          "productId": "xxx_xxx-xxxx-xxxx-xxx",
          "messageList": [
            {
              "count": 1788,
              "finalMessage": "1788 people viewed today",
              "threshold": 1,
              "order": 1,
              "messageText": "@usercount people viewed today"
            }
          ]
        }
      ],
      "importance": 1,
      "multipleMessagesEnabled": false
    }
  ],
  "error": null
}

Response Metrics Description

experienceId: It is the unique ID available for an experience.

  • For example: https://qa.richrelevance.com/engage/socialProof.jsp#/message/8060 (In this URL, 8060 represents the experience ID).

  • variationId: It is the unique ID available for a variation under the experience.

    For example: https://qa.richrelevance.com/engage/socialProof.jsp#/message/8060/5385 (In this URL, 5385 represents the variation ID.

  • locationSelector: It is the selector of the element for which the social proof message is inserted on the page. To place the message at the right location, it is important to identify the right UI component & identifier and use that parameter for inserting the social proof message. For a given location selector, the highest importance social proof experience will be considered.

  • displayDuration: It is the duration for each social proof message specified in milliseconds when multiple messages are enabled. Default value is 5000 milliseconds (5 seconds).

  • count: This is the user count or event count selected as part of the social proof experience setup.

  • messageText: This is the message text defined as part of social proof experience for each message type (metric & interval).

  • threshold: This is the threshold defined as part of the social proof experience for each message type (metric & interval).

  • Final message: This is the final social proof output message. It is based on the text with user count or event count parameter replaced by count value.

Response Codes Description

Code Description

500

Bad request because of wrong parameter name or value

400 Invalid API key or invalid event type
200 Successful operation; returns SP metrics

How Social Proof Experience Output API Works

Using social proof setup configurations for server-side or mobile app through an API to know what to show in a given variation, so that the user only needs to define how to display the social proof message.

  • Focuses on active Social Proof experiences - those currently active or Evergreen.

  • The Importance of the experience plays a key role when there are multiple conflicting experiences in a given context.

    • Automatically picks the experience with the highest Importance when multiple experiences share the same location selector.

    • If the location selector is null, It picks the highest importance experience and show it as part of the response.

    • If the location selector and importance are the same, then it picks a message randomly.

  • Identifies the right experience/variation based on context and segment parameters passed from the API call.

  • Identifies the threshold based on the user count or event count parameter from the message text.

  • Identifies the event count or user count through the SP API for the given product and identify the final text to be shown.

  • Only one message type can be selected for category/list pages currently.

  • For category/list page templates, multiple product IDs can be passed. However multiple messages cannot be provided for a single product when multiple products are passed. It is a limitation of social proof API.

    For more details about how to set up the social proof experience, refer to Social Proof User Guide.

The following few parameters are optional that also can be supported and passed to the API endpoint:

Name Required or Optional Description
cn Optional

Category Name that are currently being viewed, ready to display to the user.

searchTerm

Optional

The search term typed in by the customer. You can also use the productId parameter to provide product IDs of the products in the search results.

Example: searchTerm=adriana lima

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 to 95.50)

categoryData

Optional

Omits category data (categoryIds and categories) when set to false. The default is true.

Example: categoryData=false

pref

Optional

Referring page’s URL, may exist on every page. Shopper’s referrer prior to viewing the page. Used for reporting and merchandising. This is highly recommended.

Example: pref=http://www.google.com

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 Algonomy system. Use the pipe "|" character to separate the product IDs. Example: recentlyPurchased=uv2345|xt1234

userAttribute

Optional

Custom keys and values that describe the current customer. Separate information using a semicolon and the pipe "|" character.

Example: userAttribute=eye_color:blue;green|hair_color:brown

atcid

Optional

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

attribute

Optional

Product attribute

  • Was this article helpful?