Consumption of Marketing Recommendation Cache service API from SAP Cloud Platform with code sample

[mourad_mourad]

Background

SAP Marketing Cloud enables you to create recommendation models that provide consumers with relevant recommendations across multiple sales channels. The logic of how recommendation models return recommendations can be determined using a combination of algorithms that are part of the standard delivery, or custom algorithms that you provide.

The recommendations can be used directly in marketing campaigns or externally consumed through APIs. For example, recommendations can be provided for the items the consumer is currently looking at based on products which are often bought together.

The Marketing Recommendation Cache service is available on the SAP API Business Hub. The service enables SAP Marketing Cloud customers to provide recommendations to virtually any client system. Find out more about the advantages of this service on the Consuming Recommendation Models Using an OData Service help page.

This blog post provides an example of how to use simple html and JavaScript code to consume the Marketing Recommendation Cache service to receive SAP Marketing Cloud product and offer recommendations.

 

Product and Offer Recommendation Business Scenario

SAP Marketing Cloud covers multiple marketing scenarios including the recommendation of products or offers in a Commerce Marketing business scenario. Using a public OData RESTful API, external commerce applications can obtain product or offer recommendations from the SAP Marketing Cloud through the SAP Cloud Platform. The commerce applications consume the recommendation API and convert the results into a carousel display of the tops selling products on a web page using a sample code snippet. 

 

For example, the following can be displayed on a web page:

Product Recommendation Carousel

Offer Recommendation Banner (with auto-rotating banner)

Offer Recommendation Carousel

Prerequisites

You have configured a recommendation scenario and model using the Recommendation Scenarios and Manage Recommendations apps. For more information, see the following:

• Creating and Maintaining Recommendation Scenarios


• Manage Recommendations


• Implementing Scenario: Top Sellers on a Web Home Page


• Provide Offer Recommendations on a Web Page

 

Procedure

To implement the business scenario, you must do the following: 

• Access this link to get the source code.


• Use the html <script> tag inside the html page to load the javascript file.  You can refer to snippet_example.html in the github repository.

Please use the following example for the different use case:

• 
  
  
  
  • Product Recommendation Carousel: 
  
  
  
  

<script src=”resources/reco_product_carousel.js”></script>

• 
  
  
  
  • Offer Recommendation Banner:
    
  
  
  
  

<script src=”resources/reco_offer_banner.js”></script>

• 
  
  
  
  • Offer Recommendation Carousel:
    
  
  
  
  

<script src=”resources/reco_offer_carousel.js”></script>

• Supply the appropriate parameters within the script.

 

The Product Recommendation Carousel script contains the following parameters: 

 

Parameter	Required	Data Type	Description
carouselId	Yes	String	The ID of the div where products recommendations will be inserted
orientation	No	String	The carousel orientation. The carousel can be either <vertical> or <horizontal>. By default,the orientation is horizontal.
fontColor	No	Hexadecimal <#XXXXXX>	The font color of the recommendation text expressed as an RGB hexadecimal format <#XXXXXX>. By default, the font color is #000000 (black).
userType	No	String	The type of ID used for the UserId.
userId	No	String	The user ID, depending on the specified user type. This parameter is ignored if the Secure User ID checkbox is checked in the custom Recommendation Scenarios app.
leadingItemIds	Only for association algorithms.	String	The comma-separated product IDs to be passed to the recommendation scenario.
leadingItemType	Only when leading item IDs are provided.	String	The product type (origin) as defined in SAP Marketing Cloud.
basketItemIds	No	String	The comma-separated product IDs which are already in the cart.
basketItemType	Only when basket Item IDs are provided.	String	The product type (origin) as defined in SAP Marketing Cloud.
context	No	String	The context parameters as configured in SAP Marketing Cloud. For example, interaction type, interaction contact type, or any of the other algorithm data source pre-filters (standard delivery or custom). For more information, see Algorithm Data Source Prefilters and Recommendation Data Source Prefilters.
server	Yes	String	The SAP Cloud Platform application URL.
language	Yes	String	The language to use for the product master data retrieval. For example, “EN”, “DE”, etc...
l54	Yes	String	Encrypted key information (part of the security string).
h	No	String	User SALT to be supplied when Secure User ID checkbox is checked in Recommendation Scenarios app.
k13	Yes	Integer	Secret key version (part of the security string).
v	Yes	Integer	Version of the validation (part of the security string).
k14	Yes	String	Generated HMAC string from the key information (part of the security string).

 

The Offer Recommendation Banner script has the following parameters:

Parameter	Required	Data Type	Description
RecoOfferId	Yes	String	The ID of the div where products recommendations will be inserted
userType	No	String	The type of ID used for the UserId.
userId	No	String	The user ID, depending on the specified user type. This parameter is ignored if the Secure User ID checkbox is checked in the custom Recommendation Scenarios app.
leadingItemIds	Only for association algorithms.	String	The comma-separated product IDs to be passed to the recommendation scenario.
leadingItemType	Only when leading item IDs are provided.	String	The product type (origin) as defined in SAP Marketing Cloud.
basketItemIds	No	String	The comma-separated product IDs which are already in the cart.
basketItemType	Only when basket Item IDs are provided.	String	The product type (origin) as defined in SAP Marketing Cloud.
context	No	String	The context parameters as configured in SAP Marketing Cloud, e.g.: Interaction Type, Interaction Contact Type.
language	No	String	The language to use for the Offer Content data retrieval. For example, “EN”, “DE”, etc...
position	No	String	The Position Type of the offer content to recommend.
communicationMedium	No	String	The Communication Medium of the Offer Content to recommend.
offerContentType	No	String	The Offer Content Type to recommend.
withCoupon	No	String	‘X’ – Only Offer with Coupon ‘’ – Only Offer without Coupon
marketingArea	No	String	The Marketing Area to recommend.
server	Yes	String	The SAP Cloud Platform application URL.
l54	Yes	String	Encrypted key information (part of the security string).
h	No	String	User SALT to be supplied when Secure User ID checkbox is checked in Recommendation Scenarios app.
k13	Yes	Integer	Secret key version (part of the security string).
v	Yes	Integer	Version of the validation (part of the security string).
k14	Yes	String	Generated HMAC string from the key information (part of the security string).

 

The Offer Recommendation Carousel script has the same parameters as mentioned above for the Banner script, in addition to the following:

Parameter	Required	Data Type	Description
offerCarouselShowNumOffers	Yes	Integer	Number of offers to show in the carousel (Not applicable for banners)
offerCarouselBoxColor	No	Hexadecimal <#XXXXXX>	The color of the recommendation box expressed as an RGB hexadecimal format <#XXXXXX>.  (Not applicable for banners)
fontColor	No	Hexadecimal <#XXXXXX>	The font color of the recommendation text expressed as an RGB hexadecimal format <#XXXXXX>. By default, the font color is #000000 (black). (Not applicable for banners)

 

 

We hope this example of consuming SAP Marketing Cloud Recommendations will be useful for you. You can of course adapt and expand this example to meet your specific business and technical requirements. Please give us your feedback in the comments section.