Skip to main content
RichRelevance

How to Use Social Proof API

The RR Server Social Proof APIs are essential to display Social Proof messages, details of how to use these APIs are described in the following sections with examples.

How to obtain API key

To locate and obtain an API Key of a client’s eCommerce site:

  1. Log in to Omnichannel Personalization.
  2. On the Omnichannel Personalization Dashboard page, in the left pane click the Customer Site Name drop-down and then select the required client name.
  3. Click clipboard_ee4ab0253f55d34d9d5136af38cf101db.png available next to the Customer Site Name drop-down. The Site-info window is displayed.

    clipboard_e06fa009c49575d9e17e5cba35c9f6a26.png

  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/productEventsMetrics/spEvents?apiKey={apiKey}&productId={productId}&eventType=eventType}&timeWindow={timeWindow}&s={sessionId}&u={userId}&rcs={remoteCookieStoreValue}

Request Call Parameters

The following parameters are used for RR-Server SP-API.

Name Data Type

Param

Mandatory?

Default Value Supported Value Description

apiKey

String

Yes

NA

Valid API key corresponding to the site.

Unique valid API key for the site.

productId

String

Yes

NA

Single or multiple values can be passed using pipe delimiter '|'. 

For example, xyx | abc | pqr.

Product ID of the Item page, or all product IDs of the category page separated by '|'.

eventType

String

For multiple productId

All (Views/ purchases/ add-to-cart) 

Views/purchases add-to-cart.

Note: With multiple product IDs, only one event type is allowed.

Views/purchases/
add-to-cart events.

timeWindow

Integer

For multiple productId

All (15/60/ 720) 

15/60/720

Note: With multiple product IDs, only one time window is allowed.

Any one supported time window in 15 mins, 60 mins (1 hour), and 720 mins (12 hours).

 u

String

Yes, if mvt seed type =

external user ID

                         NA

Extracted from

window.R3_COMMON.userId

External user-Id  

  s

String

Yes, if mvt-seed-type =

external session ID

                         NA

Extracted from 

window.R3_COMMON.sessionId

External session-Id  

rcs

String

Yes, if mvt-seed-type = RR User GUID

                         NA

Extracted from browser cookie set by client in rr_rcs

rcs(remote cookie store)

Sample Response

{
  "siteId": 1810,
  "productMetrics": [
    {
      "productId": "34523454",
      "metrics": [
        {
          "eventType": "views",
          "timeWindow": 720,
          "siteDenotedUserIdCount": 90,
          "eventCount": 92,
          "isTopProduct": true,
          "isPersonalizedForLastVisit": false
        },
        {
          "eventType": "views",
          "timeWindow": 15,
          "siteDenotedUserIdCount": 8,
          "eventCount": 8,
          "isTopProduct": true,
          "isPersonalizedForLastVisit": false
        },        
        {
          "eventType": "purchases",
          "timeWindow": 720,
          "siteDenotedUserIdCount": 14,
          "eventCount": 16,
          "isTopProduct": true,
          "isPersonalizedForLastVisit": false
        },
        {
          "eventType": "purchases",
          "timeWindow": 60,
          "siteDenotedUserIdCount": 10,
          "eventCount": 12,
          "isTopProduct": true,
          "isPersonalizedForLastVisit": false
        }        
        {
          "eventType": "atc",
          "timeWindow": 720,
          "siteDenotedUserIdCount": 22,
          "eventCount": 24,
          "isTopProduct": true,
          "isPersonalizedForLastVisit": false
        },
        {
          "eventType": "atc",
          "timeWindow": 60,
          "siteDenotedUserIdCount": 11,
          "eventCount": 12,
          "isTopProduct": true,
          "isPersonalizedForLastVisit": false
        }
      ]
    }
  ]

Response Metrics Description

  • SiteDenotedUserIdCount: It is the unique user count based on mvt-seed-type id. This is part of Site Configurations RR.
  • eventCount: It is the purchase/add-to-cart event count for the eventType and timeWindow.
  • timeWindow: It is the time interval of user's last visit to the nearest interval available.
  • isPersonalizedForLastVisit: It is a flag for personalized messaging which is set to true or false according to the match of user's last visit and the nearest timeWindow.

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.

Valid API Call Examples

Without eventType & timeWindow

Note: This call is currently used for item-page.

https://recs.richrelevance.com/rrserver/api/productEventsMetrics/spEvents?apiKey=b94cb8fe7be1ff1c&productId=V_87654321

For Purchase Event

https://recs.richrelevance.com/rrserver/api/productEventsMetrics/spEvents?apiKey=b94cb8fe7be1ff1c&productId=V_87654321&eventType=purchases

For One Hour Time Window

https://recs.richrelevance.com/rrserver/api/productEventsMetrics/spEvents?apiKey=b94cb8fe7be1ff1c&productId=V_87654321&timeWindow=60

For Purchase Event with One Hour Time Window

https://recs.richrelevance.com/rrserver/api/productEventsMetrics/spEvents?apiKey=b94cb8fe7be1ff1c&productId=V_87654321&eventType=purchases&timeWindow=60

For Multiple Product IDs

For product-id: V_01234567 & V_87654321 for purchase events with 12 hours’ time window

https://recs.richrelevance.com/rrserver/api/productEventsMetrics/spEvents?apiKey=b94cb8fe7be1ff1c&productId=V_01234567|V_87654321&eventType=purchases&timeWindow=720

Personalized Messaging on Shopper's Interactions with a Product and Page

Social Proof now provides personalized messages to a shopper about other shoppers’ interactions on the app which include product page viewed, product added to cart (ATC), and product purchased by the other shoppers since the last visit of the shopper.

For example, a personalized message to a shopper showing interaction of other shoppers with a product looks like this: “25 people purchased this item since your last visit”. Another example is: “45 people visited this page since your last visit”.

If a shopper visits a product page second time within certain hours span, such personalized messages are displayed for them on their second visit. These messages provide engagement with the product and generate high confidence among the shoppers.

Metrics ViewsATC, and Purchases are captured for every 2-hour interval and mapped to the user's last visit to the nearest interval available. The metrics are available for products for every 2, 4, 6, 8, 10, 12, 14, 16, 18, 20, 22, and 24 hours as a dynamic experience.

For example, if a shopper visits a product’s page 7.5 hours after their first visit, then the nearest interval that matches the shopper’s second visit falls between 6-hour and 8-hour intervals. Thus, the views, ATC, and purchases of the 8-hour interval are considered and shown as part of the personalized messages to the shopper.

Clients can also change dynamic experience for ‘today’ metrics from 24 hours to 12 hours.

API perspective

For each product, the following metrics are captured for each Metric/Interval.

  • Views (event type)

  • 1440 minutes or 24-hour interval (time window)

clipboard_e607b6b6e7a20bd065bd847c31c0c899c.png

When user's last visit (7.5 hours ago) matches the nearest time window (8 hour window), then the flag IsPersonalizedForLastVisit is set to true. The views/ATC/purchases with the flag as true are the metrics for personalized messaging for the item page for the user.

Event Count Vs User Count

There are two ways to show the count of product views, add to cart, and purchases:

  • Number of people interacted with the product

  • Number of events associated with the product

By default, user count is used as a metric for social proof messaging. However, it can be changed from user count to event count (currently through JavaScript and through UI in the future).

Showing number of people interacted with the product

The number of people interacting with the product is captured in real-time:

  • Views Right Now: The number of people who viewed the product for the last 15 minutes are captured (It refreshes every 45 seconds).

  • Add To Cart (ATC)/Purchases: The number of people who added the product to the cart and purchased are captured for every 1 hour/60 minutes (It refreshes every 1 min).

  • Views/ATC/Purchases Today: The number of people who viewed/added to the cart/purchased is captured every for 12 hours/720 minutes (Today).

From the API, SiteDenotedUserIdCount provides the user count (number of people interacting).

clipboard_eb4315172ac09d45394368553cbf04dc5.png

Showing number of events (Views/ATC/Purchases) associated with the product

From the API, eventCount provides the number of views, products added to the cart, and the number of purchases.

clipboard_eb1ed491e1a4854b384e2c4f8460e288e.png

Difference between eventCount and SiteDenotedUserIdCount

When 1 user makes 10 purchases, it results in the following:

  • User Count (siteDenotedUserIdCount) = 1

    When the user count metric is used, then the number of users is shown.

    For example, X people are purchasing this product right now.

  • Event count (eventCount) = 10

    When the event count metric is used, the number of purchases is shown.

    For example, X purchases right now.

Social Proof API for 7 Days Interval

The 7 days interval enables the API response to include the metrics - Views/ATC/Purchases for the intervals of 2 days, 3 days, 4 days, 5 days, 6 days, and 7 days along with the existing intervals - Right Now/Last 1 hour/Today.

Note: The 7 days interval feature is not enabled by default for all the customers, hence contact the Algonomy Support Team to enable this feature.

API Response Examples

  • For 2 days interval (timewindow = 2880 Min)

clipboard_e43bd3696de9b18768446fd5d4d8b61c4.png

  • For 6 days interval (timewindow = 8640 min)

clipboard_ee30179ce431b37e756731a4033ed574e.png

  • For 7 days interval (timewindow = 10080 min)

clipboard_efb70f0b13093e8b82df392fb2ee440bd.png

The event count and user count are calculated as the sum of today’s count (from 0 hour to current time) + Last days count

For 7 days Interval = Today’s count + Last 6 days count

Inventory Messaging in Social Proof API

Social Proof API response includes Inventory remaining as a new parameter. It is calculated from Inventory Quantity (come from catalog feed) and the purchases that have happened from the last update of the inventory quantity. It is added as inventory messaging to persuade users to purchase. Inventory depends on providing inventory level for products in the catalog.

Customers should send both Inventory Quantity and Inventory Updated Time through Catalog feed and set the site configuration parameters with the names of the fields that they send through the feed.

Social Proof Inventory Messaging is to display an estimate of total available inventory quantity for a given siteId and productId combination at any point of time. At RR server, in the existing implementation, when it receives sp-events-metrics response from sp-api, a new field inventory quantity will be added and sent as a final response.

The product catalog needs to include the following to identify the attributes used for inventory messaging:

  • Inventory level : By default, the key name defined in the site configuration for inventory level is 'inventory_quantity'.

  • Timestamp for inventory level: By default, the key name defined in the site configuration for inventory timestamp is 'inventory_quantity_update_time'.

Site Configuration for Inventory Message

Perform the following steps to set up the site configuration of Inventory Messaging:

  1. On the Omnichannel PersonalizationDashboard page, go to Admin > Site Configurations RR.
  2. In the search box, type 'inventory' to view the inventory related configurations.

  3. In the other site configurations area, specify the following keys:

    • inventory quantity key: Click  and specify the key as inventory_quantity.

    • inventory quantity update time key: Click  and specify the key as inventory_quantity_update_time.

    Note: The customers either can provide their own key name or keep the default key name displayed in the placeholder.

  4. Based on the values shared, the inventory quantity is estimated considering the purchases that happened for a particular time period. If no purchases are present, then set the values as displayed.

  5. Restart the core/rrserver module.

Use Cases

Following are the use cases for Inventory Messaging:

  • Use Case 1: inventoryQuantityComputed time Window = 60min(1hr)

    Inventory Quantity = 500

    Event count = 150

    feed time = 21:45 on 12 th oct

    Cassandra time = 22:55 on 12 th oct (Cassandra time should be less than 1 hr(feed time - cassandra))

    API Hit = 22:15 on 12 th oct - showing 500 quantity diff time (30)

    API Hit = 22:27 : showing 400 Diff time (42 min)

    API Hit = 22:35 : showing 400 Diff time (52 min)

    API Hit = 22:45 : showing 400 Diff time (60 min) - 1h

    API Hit = 23:00 : showing Diff time 400 (75 min)

    API Hit = 23:15 : showing 400 Diff time (90 min)

    In the sp api result inventory count is showing as 400

  • Use Case 2: inventoryQuantityComputed time Window = 120min(2hr)

    Inventory Quantity = 500

    Event count = 150

    feed time = 21:45 on 12 th oct

    Cassandra time = 23:30 on 12 th oct (Cassandra time should be less than 2 hrs(feed time - cassandra))

    API Hit = 23:30 : showing 350 Diff time (105 min)

    API Hit = 23:45 : showing 350 Diff time (120 min) - 2 hrs

    API Hit = 00:00 : showing 350 Diff time (135 min)

    API Hit = 00:15 : showing 350 Diff time (150 min)

    API Hit = 00:30 : showing 350 Diff time (165 min)

    API Hit = 00:45 : showing 300Diff time (165 min)

    In the sp api result inventory count is showing as 350

  • Use Case 3: inventoryQuantityComputed time Window = 240min(4hr)

    Inventory Quantity = 500

    Event count = 200

    feed time = 21:45 on 12 th oct

    Cassandra time = 1:30 on 13 th oct (Cassandra time should be less than 4 hrs (feed time - cassandra))

    API Hit = 1:00 : showing Diff time (195 min)

    API Hit = 1:15 : showing Diff time (210 min)

    API Hit = 1:30 : showing 300 Diff time (225 min)

    API HIt time = 1:45 showing 300 Diff time (240 min) - 4hrs

    In the sp api result inventory count is showing as 300**

  • Use Case 4: inventoryQuantityComputed time Window = 360min(6hr)

    Inventory Quantity = 500

    Event count = 250

    feed time = 21:45 on 12 th oct

    Cassandra time = 3:30 on 13 th oct

    API HIT = 2:48 on 13 th oct showing 250 Diff time (303 m)

    API HIT = 3:45 on 13 th oct showing 250 Diff time (360 min) - 6hrs

    In the sp api result inventory count is showing as 250**

  • Use Case 5: When time difference is between 0 to lowestInterval/2

    Total quantity is displayed in the feed time.

  • Use Case 6: When time difference is greater than the maximum window interval available.

    The Inventory Quantity is displayed as -1.

Social Proof Messaging with Dynamic Count Parameters

This section provides information on how to incorporate dynamic count parameters into social proof messaging. The dynamic count parameters include user count and event count which allow you to display the number of users or events associated with a product in your social proof message. Additionally, this section also explains how to switch between using user count and event count as a metric in the social proof message.

Dynamic Count Parameters

The dynamic count parameters enable you to include the count of users or events in your social proof message. By default, the text includes the user count parameter as "@usercount people viewed today". However, you can place the "@usercount" parameter anywhere within the message text. This allows you to customize the message according to your requirements. For example, if you want to display a message like "Popular! 10 people viewed today," you can modify the text as "Popular! @usercount people viewed today".

Social Proof Metrics

Social proof provides two types of metrics for product interactions which are user count and event count. These metrics help to demonstrate the popularity and engagement associated with a product. The metrics can be used to track product views, adds to cart, purchases, and inventory.

  • User Count: This metric represents the number of unique individuals who have interacted with the product.

  • Event Count: This metric indicates the total number of events associated with the product including all interactions.

Switching Metrics

By default, the user count is used as the metric for social proof messaging. However, you have the flexibility to switch between using user count and event count based on your preference. When you change the metric, the corresponding count will be used for both the message text and the threshold.

To update the message text to display the event count, you can use the following formats:

  • "@eventcount views today"

  • "Popular! @eventcount views today"

By incorporating the "@eventcount" parameter in the message text, you can showcase the event count in your social proof message.

Threshold Selection

When determining the threshold for social proof messaging, the same metric used in the message text will also be utilized. For instance, if you choose to display the user count in the message text, the threshold will be based on the number of users. Similarly, if the event count is included in the message text, the threshold will be based on the number of events.

Note: Ensure that the chosen metric aligns with your intended message and accurately reflects the desired social proof for your product.

Mapping Page Types

The following page types are mapped to the appropriate templates as listed below. Once the page type is selected, social proof message should show appropriately based on the template that is mapped.

Page Type Template
Add To Cart Page Item Page
Brand Page List Page
Cart Page List Page
Category Page List Page
Email Page None
Generic Page None

Home Page

None

Item Page

Item Page

Purchase Complete Page

None

Search Page

List Page

 

Tracking Social Proof Messages through Experience API call (Actual Messages)

Implementing detailed tracking of social proof messages through the Experience API enables a more thorough analysis of message effectiveness. The Experience API to provide detailed insights into the display of social proof messages to shoppers. By specifying the exact message displayed, the API facilitates a comprehensive analysis of message effectiveness, enabling data-driven optimization strategies. The Experience API offers enhanced granularity by conveying specific information about the displayed message. This includes the following scenarios:

  • Single Message Display: The API will now pass the actual social proof message displayed when the threshold is met.

    For example, SP Message shown - Actual Social Proof Message.

  • Multiple Message Display: When multiple messages meet the threshold, the API will append a note indicating eligibility for multiple messages, along with the actual message displayed.

  • No Message: If the threshold criteria are not met and no social proof message is displayed, the API will indicate "No Message - threshold not satisfied".

  • Error Handling: Clear error messages will be provided in case of any issues encountered.

Enabling Multiple Metrics for Multiple Products

The Social Proof API enables to display multiple messages across Add-to-Cart, Category, and Item pages, overcoming the limitation of showing only one message for multiple products. This enhancement allows for the presentation of several messages that meet the threshold as part of social proof messaging. Additionally, the API supports multiple products for various intervals and event types, aligning with the functionality available for Item pages. It can handle up to 100 products on Category and Search pages and less than 15-20 products on Cart pages, catering to the diverse needs of digital storefronts.

Social Proof Supporting Recommendation Placements

Social proof is enhanced to engage users and boost click-through rates through the inclusion of social proof messaging within product recommendations. This feature enables you to show more than one social proof message on the same page type, to show social proof messages using the 'List page' template on product recommendations and ensuring that users see messages relevant to their current journey. The importance of these messages is determined by placement type and template type, allowing you to deliver a customized experience.

Configuring social proof messaging is simple, with templates aligned with the existing list page configurations. You can specify where messages are applied by entering placement names, ensuring precise control over message placement. This enhancement empowers you to provide users with context-aware content, improving their shopping experience and increasing engagement.

Social Proof messaging can be displayed on the recommendations on any of the pages. Selecting the location (anchoring element type & attribute) is the only element that drives the social proof messaging.

  • Showing Social Proof Messaging on Item Page Recommendations

    The client needs to select placement context along with the page type so that the social proof message can be shown on the recommendation placements.

    Note: When the placement context is selected along with page type, the template will be set to the list page. Therefore, the user will only be able to select one message type in this case.

  • Showing Social Proof Messaging on List Page Recommendations (or any other pages)

    The location selector is the only element that drives the social proof messaging. Therefore, it does not require any setup other than selecting an appropriate unique location to the placement of social proof message that you want to show.

  • If you want only one placement to show the social proof message (out of many placements on the item page), ensure the location of the social proof message to be displayed is unique to that placement. The placement selection (in Item page template) is only to ensure the template is mapped to the list page.

Social Proof Supporting Language Parameter

Social Proof has enhanced its message display capability by introducing language parameter support. This allows merchants to specify the desired language for social proof messages, ensuring users receive messages in their preferred language. This includes the following benefits:

  • Multi-Language Configuration: Merchandisers can configure social proof messages for multiple languages using a unified template, specifying messages in the appropriate locale for each language.

  • Localized Text Entry: Users can input text for each specified language directly within the user interface, ensuring precise localization. This feature simplifies the setup and management of localized messages.

  • Dynamic Messaging Display: Social proof messages dynamically adapt to display the appropriate text based on language parameters provided in the R3_COMMON configuration. This includes support for language (lang) parameters, enabling the direct display of corresponding text when the language parameter is passed.

Language Parameter

The Social Proof Output Response API now accepts the language parameter (lang), allows to display messages in the specified language. This ensures seamless integration with applications, enabling users to receive messages in their preferred language through server-side interactions.

The 'lang' parameter enables language-specific customization within the Social Proof Output Response API. Specifying this parameter ensures that messages are displayed in the user's preferred language, enhancing the overall user experience across different locales.

{
    "name": "purchases_in_the_last_hour_threshold",
    "value": "1",
    "allowedValues": null,
    "description": "Template.socialProofingItemPage.variable.purchases_in_the_last_hour_threshold",
    "placeholder": null,
    "allowedValuesVariable": null,
    "dependentListId": null,
    "dependentByValue": null,
    "questionType": null,
    "optionsAPI": null,
    "type": "NUMBER",
    "lang-en": "@usercount viewed this today",
    "lang-de": "@usercount hat sich das heute angesehen"
}

The following points outline the key features and functionalities of the 'lang' parameter within the Social Proof Output Response API:

  • lang-en: Message template in English.

  • lang-de: Message template in German.

  • Was this article helpful?