This document explains the functional overview of Amazon Personalize and its required setup to integrate and manage Amazon Personalize in the Infosys Equinox Commerce platform and the storefront (React-based).

About Amazon Personalize

Amazon Personalize is a low-code machine learning (ML) service that can generate custom recommendations through an application program interface (API) call for any application running on Amazon Web Services (AWS) infrastructure. The goal of Amazon Personalize is to deliver customized recommendations that will improve customer engagement.

How to Integrate Amazon Personalize

You can easily integrate Amazon Personalize with the Infosys Equinox Commerce platform. A user with the business admin role should perform these steps: 

Note: For Amazon Personalize glossary of the terms, see  

Amazon Personalize Set-Up Process

The following diagram shows the steps to be followed for setting up Amazon Personalize: 

 

Setting Up Amazon Personalize API 

This section explains how to set up Amazon Personalize APIs. You need to create a recommendation solution for a store. 

To set up Amazon Personalize, 

  1. Firstly, invoke the Create Personalize API. In this request, you need to pass the store ID as JSON in the request body.
    The syntax is as follows: {“storeId”: “VALUE”}
  2. Update AWS_GATEWAY_ID with the actual API gateway ID received after deployment.

    • The API will trigger a lambda function that checks if personalize resources exist for a given store. If the personalize resources DO NOT exist, the API triggers a step function to create personalize resources.
    • Step Function creates these personalized resources such as dataset group, dataset, and event tracker for a given store ID.

Integrating Track Event Functions

Once the Amazon Personalize setup is done, the next step is to integrate track events functions. These functions capture the events and send them to the personalize engine.  

For calling the events from the storefront (built with React), use Personalize.js file. This file includes the following functions which calls the handlePutEvent API (for example, to capture interactions like customer landing on the product detailed page, product listing page, any products that are purchased, etc.) internally and capture customers who viewed or purchased items: 

  • trackQuickViewProduct: On PLP, when a customer clicks on the quick view button on a product card, this function captures that interaction as a ‘View event’. 
  • trackViewProduct: When a customer lands on a PDP, this function records that interaction as a ‘View event’. 
  • trackPurchaseProduct: When a customer makes a purchase and lands on the order confirmation page, this function captures that interaction as a ‘Purchase event’. 

In each interaction, the user ID, item ID, and time of interaction are recorded and sent to the S3 dataset via the handlePutEvent API. The interactions are used to train and/or update a recommendation solution. 

For invoking the above track event functions, refer to the steps mentioned in the “Amazon Personalize Storefront Integration” document.

Create Recommender API 

Prerequisite for Creating a Recommender 

The prerequisite for creating a recommender is that there must be a minimum of 1000 interactions record from a minimum of 25 unique user IDs with at least 2 interactions for each in the interactions dataset. 

Creating a Recommender

You can create a recommender by hitting the Create Recommender API (Application Programming Interfaces) and passing the recommender Name and store ID in the request Body. This will internally perform all operations via Step Functions. 

The following tables list the recommender names that you need to pass in the request body: 

Recommenders  Recommender Names 
Best Seller  Best-Seller 
Customers who viewed X also viewed  Customer-Who-Viewed-X-Also-Viewed 
Frequently bought together  Frequently-Bought-Together 
Most viewed  Most-Viewed 
Recommended for you  Recommended-For-You 

To create a recommender, 

  1. Navigate to the create/recommender API.
  2. Mention the storeID and recommenderName details:

  3. Check the status of the recommender. Once the recommender status is ACTIVE, the user will get recommendations.
    Note: This status can be viewed by the Infra team with the AWS account.

Get Recommendations API 

The following recommendations are available and configured in the storefront: 

  • Recommended-For-You
  • Best-Seller 
  • Most-Viewed 
  • Frequently-Bought-Together 
  • Customer-Who-Viewed-X-Also-Viewed 

Once the Amazon Personalize setup is done for a store and the interactions dataset is populated using the event tracker. Any of the recommenders could be created and consumed. The recommendations are generated and rendered according to this flow

Get Recommendations and Integrate to UI 

Prerequisite to Get Recommendations 

For getting the recommendations, the Get Recommendations API calls have to be made. These calls return a list of recommended product IDs. The API endpoint differs for each use case. 

Before using the personalize.js file, 

  1. Configure API Gateway ID or pass the complete URL as API_URL as shown in the snapshot.

  2. Call Personalize Init function internally before calling any fetch function which sets the store ID, Customer ID, and API URL.

Using the Personalize JS File

For calling the APIs from the storefront (built with React), use the Personalize.js file. It includes the following functions, which calls the Get Recommendations API internally, and gives a list of product IDs: 

  • fetchRecommendedForYou
  • fetchCustomerAlsoViewed
  • fetchFrequentlyBoughtTogether
  • fetchBestSeller
  • fetchMostViewed

Note: For more information about the Personalize.js file, refer to the “Infra Set Up document and the Storefront Integration” document. 

Reference React Storefront Implementation 

The Personalize.js fetch functions return a list of product IDs. To display products in the front end, the entire product details are required.  

To get product details from Storefront Orchestration (SFO) microservice, 

  1. Add the getSFO endpoint in the Common.js file:

  2. Add the getProductDetails function in the Catalog.js file:

  3. Call the getProductDetails function after fetching functions to get the complete product details.

  4. Pass the list of product details in the carousel to finally display the result in the storefront (built with React).

    Note: For the detailed invocation of fetch recommenders, follow the steps mentioned in the document “Amazon Personalize Storefront Integration” document. 

Configuring Store Properties 

This section explains the store properties for using the current reference React-based storefront.

The following are the flags that need to be added to the store properties. The following fields are mandatory for Amazon Personalize integration. 

  • enableEquinoxRecommendations: If it is set to true, the recommendations will be shown on the storefront.  
  • sfStoreDetails:

 The value of the store property enableEquinoxRecommendations can be true or false.

Refer to the screenshot given below: 

 

The value of the store property sfStoreDetails should be the following JSON:

{
  "associations": [ 
    { 
      "serviceName": "pricing", 
      "properties": [ 
        "currencyCode" 
      ] 
    } 
  ], 
  "store": { 
    "info": [ 
      "id", 
      "name", 
      "status", 
      "defaultShippingRegion", 
      "globalStore" 
    ], 
    "properties": [ 
      "activateB2B2C", 
      "countryConfig", 
      "tierConfigMap", 
      "PriceRuleConfigMap", 
      "allowedRewardTypesForOptIn", 
      "enableEquinoxRecommendations", 
    ] 
  } 
}

Refer to the screenshot given below:

Start/Stop and Delete Recommender API 

Once the recommender is created, you can stop the recommender for the time being when recommendations are not required. 

Stopping the Recommender 

To stop the recommender, call the Stop Recommender API with the store ID and recommender name as shown in the request:

Resuming the Recommender 

To resume the recommender operations, call the Start Recommender API as shown below:

Deleting a Recommender 

To delete a recommender, call the Delete Recommender API: 

 

 

Revision History
2023-06-13 | JP –  Page created and content uploaded for 8.14 release.