Defining Recommendation Strategies

You can use SPARQUE Desk and the Wrapper to deliver product recommendations to your application. The setup does not work with a fixed list of strategies, allowing for a high degree of flexibility. When the config Wrapper endpoint is requested, the Wrapper uses the SPARQUE Desk recommendations endpoint to determine which recommendation strategies are available.

For each strategy, a corresponding endpoint must be defined in SPARQUE Desk so the Wrapper can request recommendations. In this guide, we use a "best sold" recommendation as an example.

Configure Data Set

In most cases, a static definition of the recommendation options in SPARQUE Desk should be sufficient. Use the data definition and mapping below as a guideline.

Data Set Source

<?xml version="1.0" encoding="UTF-8"?>
<recommendations>
   <option>
      <name>recommendation_best_sold</name>
      <label>
         <code>en-US</code>
         <description>Best sold products (total and/or user specific)</description>
      </label>
      <label>
         <code>de-DE</code>
         <description>Meistverkaufte Produkte (insgesamt und/oder benutzerspezifisch)</description>
      </label>
   </option>
</recommendations>

Data Set Mapping

<?xml version="1.0" encoding="UTF-8"?>
<xsl:stylesheet version="1.0"
  xmlns:xsl="http://www.w3.org/1999/XSL/Transform"
  xmlns:su="com.spinque.tools.importStream.Utils"
  xmlns:spinque="com.spinque.tools.importStream.EmitterWrapper"
  extension-element-prefixes="spinque">
 
  <xsl:output method="text" encoding="UTF-8"/>

	<xsl:variable name="rdfstype">http://www.w3.org/1999/02/22-rdf-syntax-ns#type</xsl:variable>
    <xsl:variable name="prefix">https://www.sparque.ai/</xsl:variable>
    
	<xsl:template match="option">        
		    <xsl:variable name="recommendation" select="su:uri($prefix, 'recommendation', name)"/>
		    <spinque:relation subject="{$recommendation}" predicate="{$rdfstype}" object="{concat($prefix, 'recommendation')}"/>
		    <spinque:attribute subject="{$recommendation}" attribute="endpoint" type="string" value="{name}"/>
            
            <xsl:for-each select="label">
                <spinque:attribute subject="{$recommendation}" lang="{code}" attribute="description" type="string" value="{description}"/>
            </xsl:for-each>
	</xsl:template> 
      
</xsl:stylesheet>

Configure Strategies and Endpoints

Endpoint recommendations

This endpoint returns all available recommendation options. The Wrapper queries this endpoint when /config/ is requested. It requires a locale (string) parameter to provide localized, user-friendly names for the recommendation options.

Result description:

{
    "class": "https://www.sparque.ai/recommendation",
    "level": 1,
    "mode": "full",
    "attributes": [
        {
            "name": "description",
            "type": "STRING",
            "aggr": "most_frequent",
            "splitLanguages": true
        },
        {
            "name": "endpoint",
            "type": "STRING",
            "aggr": "most_frequent"
        }
    ],
    "constants": [],
    "includes": []
}

This will result in the following JSON output when calling the SPARQUE Desk endpoint:

{
    "offset": 0,
    "count": 10,
    "type": [
        "OBJ"
    ],
    "items": [
        {
            "rank": 1,
            "probability": 1.0,
            "tuple": [
                {
                    "id": "https://www.sparque.ai/recommendation/recommendation_best_sold",
                    "class": [
                        "https://www.sparque.ai/recommendation"
                    ],
                    "attributes": {
                        "description": {
                            "de-DE": "Meistverkaufte Produkte (insgesamt und/oder benutzerspezifisch)",
                            "en-US": "Best sold products (total and/or user specific)"
                        },
                        "endpoint": "recommendation_best_sold"
                    }
                }
            ]
        }
    ]
}

Retrieving the List of Available Recommendations

The response of the SPARQUE Wrapper endpoint /config will contain the list defined above. When the locale filter does not match a description, the strategy name itself is used as fallback.

Example:

...
    "recommendationStrategies": [    {
        "title": "recommendation_best_sold",
        "strategy": "recommendation_best_sold"
    }]
...

SPARQUE Desk Endpoint recommendation_best_sold

The SPARQUE Desk output from the recommendations endpoint includes attributes such as endpoint and description. The endpoint attribute - recommendation_best_sold in this case - must match the name of a SPARQUE Desk endpoint exactly.

You can define these endpoints with parameters if needed. When using custom parameters, provide them as query parameters to the Wrapper so that they can be forwarded to SPARQUE Desk.

recommendation_best_sold/p/user/{STRING} -> OBJ

How it Works

You can use the recommendation_best_sold endpoint by calling the SPARQUE Wrapper recommendations API and specifying the desired strategy in the StrategyString parameter. For example:

/api/v2/recommendations?StrategyString=recommendation_best_sold&WorkspaceName=myWorkspace&ApiName=myApi&Locale=en-US&UserId=myUserId&ChannelId=myChannelId&Count=10&myCustomParameter=myParameterValue

This will send the following request to SPARQUE Desk:

/1/myWorkspace/api/myApi/c/myCustomParamter/myParameterValue/c/UserId/myUserId/c/locale/en-US/c/channel/myChannelId/q/recommendation_best_sold/e/user_product_catalog/results?config=default&count=10&offset=0