Prerequisites

Getting API Key

Perform the following steps to get the API Key belongs to the required client site:

  1. Log in to Omnichannel Personalization.

  2. On the Omnichannel Personalization Dashboard page, in the left pane, click the Customer Site Name dropdown and then select the required client name.

  3. Click available next to the Customer Site Name dropdown.

    The Site-info window displays the API Key and Site Id.

  4. From the Site-info window, copy the 'API Key' and save it to your drive. You will need this key while injecting JavaScript on the client site.

Getting API Client Key

Note: Contact Algonomy Support Team to get the API Client Key.

Recommendation Placements Prerequisites

Following are the prerequisites for enabling the recommendation placements:

  • Client.js should be available.

  • R3_COMMON parameters should be passed as required from the documentation.

  • The web URL must allow to embed in an iframe of richrelevance.com. Majorly two points where the clients block us:

    • Content Security Policies

    • Access Control Allow Origin

MVT seed type needs to be passed as an input parameter. Based on the client's MVT seed type, one of the following parameters should be available as part of the R3_COMMON variables:

  • External Session ID: This is the external session ID.

    • Set a global R3_COMMON object that contains the required key values which will evaluate and render the respective Social Proof Dynamic Experience.

  • External User ID: This is the external user ID.

  • RR User GUID: This is the user's globally unique identifier.

The best practice is to pass all three IDs (External Session ID, External User ID (if available), and RR User GUID (via rcs)). If it is not available, the client should pass at least the MVT seed type.

Following conditions are considered on social proof implementation:

  • If the client has server-side integration for Recommend and other modules, then the social proof is to be implemented by the client side.

    • MVT seed type=RR User GUID

      • In this case, the client has to make the rr_rcs (rcs cookie) available for the client.js.

      • If the rr_rcs cookie is “http only”, then client.js will not be able to get/read rr_rcs from the browser cookies, so the client should remove “HTTP only” by client.

      • Once the rr_rcs cookie is available for client.js, all the API calls (targeting, experience, and social proof APIs) will have the rcs param as part of the API calls.

    • MVT seed type=External Session ID

      • In this case, the client should be able to pass session ID as part of R3_COMMON parameters during script injection on the site.

  • If the client has client-side integration for Recommend and other modules, then the social proof is to be implemented by client side.

    • MVT seed type=RR User GUID

      • In this case, Algonomy will make the rr_rcs (rcs cookie) available for the client.js (By default, this will not set “http only”).

      • Once the rr_rcs cookie is available for client.js, all the API calls (targeting, experience, and social proof) will have the rcs param as part of the API calls.

    • MVT seed type=External Session ID

      • In this case, the client should be able to pass session ID as part of R3_COMMON parameters during script injection on the site.

For injecting JavaScript on the client site, see Injecting JavaScript on Client Site.

Note: Any context parameters that are defined as part of the social proof experience, they should be made available as part of the R3_COMMON variables. And share the reference of SP new API to know what those parameters are and what is the variable they need to pass.

Enabling Output of Social Proof Message Through a Function

  • If variable is “abc”, by entering window.RR.abc in console, the output of social proof messaging will be made available.

  • For clients who want to use Dynamic Experiences but want to render it themselves, they can make use of social proof experience output through this variable and render the message themselves.

    Note: This process is applicable only for the client side.

R3_COMMON Parameters

To efficiently utilize the R3_COMMON parameters, refer to the documentation How to Use Social Proof Experience Output API . This section outlines all the supported parameters and their appropriate usage based on the context and segments added in the social proof experience.

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.

Supported Parameters

The supported parameters for the API include both required and optional fields, essential for tracking customer behavior, personalizing shopping experiences, and enhancing reporting and analytics.

Name Required or Optional Description

apiClientKey

Required

A unique key specific to each API implementation. It identifies the specific application or client for reporting, permissions, and merchandising. This is provided by Algonomy.

Example: apiClientKey=b0126f995ac848159d

apiKey

Required

A unique key that identifies the site. Each Algonomy client has a unique API key to separate data and traffic from other clients. This is provided by Algonomy.

Example: apiKey=4faeaf752ee40a0f
userId Required when available

User ID. A unique string to identify each customer (user). All customer behavior is stored using this key. It is case-sensitive and should be the same user ID sent to Algonomy in other applications.

Example: userId=0982347
sessionId

Required

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
placements

Required

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

For example: item_page, cart_page, and category_page.
productId

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.

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 and it is required when the mvt seedType is rruserguid.

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 that the product belongs to. The value must match the external ID provided by the merchant to Algonomy for the category.

Example: categoryId=902312

regionId (or) region

Optional

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

Example: regionId = <region id value>

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.
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
categoryName

Optional

The category name that the product belongs to.

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
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
segments

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
userAttribute

Optional

Custom keys and values that describe the current shopper. 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
categoryData

Optional

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

Example: categoryData=false

Note: excludeAncestor=false can be used to include the ancestor data.