Developer Considerations for Explicit Recommendations

Product recommendations are considered best practice. Use explicit recommendations if necessary.

Existing Applications and Explicit Recommendations

Some Salesforce B2C Commerce storefront applications were developed using the product linking feature. This feature pre-dated the explicit recommendations feature in Business Manager and requires added considerations.

Define product-to-product relationships to provide for replacement products, cross-sells, up-sells accessories, follow-up, a different order unit or spare parts. With the product linking feature, you define simple links between products. For example, linking older versions of a product with newer versions.

If you use the product links feature, you don’t need to convert to the recommendations feature. B2C Commerce also supports product linking. However, enhancements are made only to the recommendations feature.

With a product linking and explicit recommendation implementation, you can:

Create added recommendation types through custom attribute definitions.
Define the presentation logic for the additional recommendations within UX Studio in your storefront cartridge.

When using both features, keep the following in mind:

Product links conceptually are intended for fundamental relationships between products. For example, product-to-part relationships.
Recommendations can appear only on a site if the storefront catalog contains the recommendation. Product links aren’t directly stored in a catalog and don’t have this restriction.
Recommendations are system objects and can have custom attributes. Product links can’t have custom attributes.

Some reasons for moving away from a product linking implementation and switching to or adding recommendations include:

Implementing category to product recommendations.
Using recommendation-specific attributes (for example, name, short description, long description, callout message, or image). These attributes let you customize the presentation of a specific product based on the target object and recommendation type.

Developer Best Practices for Explicit Recommendations

When working with Explicit Recommendations, use these developer best practices.

When working with your merchandising team:

Make sure to provide the team with a clear understanding of how explicit recommendations are implemented within their storefront. It helps merchandisers to understand various use cases including:
- Not defining any recommendations.
- Defining more than the specified number of recommendations.
- When imports are scheduled (if using the recommendation import functionality). This information is important for building imports into business process time and allowing for validation and augmentation as necessary.
When using variation products, make sure to understand whether to assign recommendations to the base product, variation products, or both. How you assign these products affects how these products appear in the storefront.

As shown in the SiteGenesis application, it is important to note that the default behavior is to show recommended products regardless of availability. Because of this default behavior, we suggest that you change your application to show recommended products only if they are in stock.

General Considerations for Explicit Recommendations

When determining how to implement explicit recommendations, consider these planning and development phase guidelines.

These guidelines include considerations for the following phases:

Requirements phase
Design phase
Build phase
Development and test phase

During the requirements phase, you idenfify how many types of recommendations are required for the solution. For each identified recommendation type, first determine requirements for the following:

Presentation logic: Where each recommendation type renders, how many recommendations are presented at a time. This determination includes what occurs when:
- No recommendations are defined for a given category or product.
- Fewer than the planned number of recommendations are defined for a given category or product.
- More than the planned number of recommendations are defined for a given category or product.
Visualization requirements: How individual recommendations appear and what data elements are required to support any specific visualization.

After making these determinations, identify how you want recommendations populated (import, manual, programmatic, or other). Populate recommendations during development or when the site is live.

If you plan to manually create recommendations in Business Manager, make sure to identify the following:

Who creates and maintains the recommendation.
Any necessary review process.
How to test the recommendation.
How recommendation data is replicated with catalog data.

If you plan to import recommendations, define the import process. If possible, implement this process as a job within Salesforce B2C Commerce to take advantage of the scheduling and notification functionality built into the system.

After you solidify information in the requirements phase, move on to the design phase. During this phase, consider the operational overhead and merchant ease of use.

Consideration	Description
Operational overhead	Review the day-to-day operational overhead associated with creating and maintaining recommendations manually within the system―especially if you have large product catalogs. Determine whether you require that all products appear with explicit recommendations; if you do, consider whether it would be advantageous to add simple logic into the presentation rules. If you plan to build logic into B2C Commerce to dynamically determine which products to recommend, pay attention to any additional page rendering overhead. Additional overhead can negatively impact storefront performance. Make sure to consider what to populate as part of the import process using logic based on existing attributes and category assignments.
Merchant ease of use	Make sure you know the product or category ID. This information helps you search more accurately within the Business Manager Recommendations module. Make sure these values are meaningful to your organization.

Consideration

Description

Operational overhead

Review the day-to-day operational overhead associated with creating and maintaining recommendations manually within the system―especially if you have large product catalogs. Determine whether you require that all products appear with explicit recommendations; if you do, consider whether it would be advantageous to add simple logic into the presentation rules. If you plan to build logic into B2C Commerce to dynamically determine which products to recommend, pay attention to any additional page rendering overhead. Additional overhead can negatively impact storefront performance. Make sure to consider what to populate as part of the import process using logic based on existing attributes and category assignments.

Merchant ease of use

Make sure you know the product or category ID. This information helps you search more accurately within the Business Manager Recommendations module. Make sure these values are meaningful to your organization.

Following the design phase, you enter the build phase where you build code to support recommendation requirements. You then facilitate the development and test phase:

Create users with permissions that are in line with your business processes.
Create an initial set of test recommendations.
Use a test plan to make sure that all use cases are reviewed.
Test the import process, if applicable.

Business Objects for Explicit Recommendations

Explicit recommendations use an extensible system object to include native attributes.

This table lists the native attributes included with the Recommendation system object.

ID	Type	Description	Localizable
UUID	String	The recommendation’s internal identifier.	No
calloutMsg	Html	The recommendation’s callout message.	Yes
creationDate	Date + Time	The recommendation’s creation date. This doesn’t change.	No
image	Image	The image associated with the recommendation that appears on the storefront.	No
lastModified	Date + Time	The date and time at which the recommendation was modified. This changes with each edit.	No
longDescription	Html	A detailed description of the recommendation.	Yes
name	String	The name of the recommendation as it will appear on the storefront.	Yes
RecommendationType (see below)	Enum of Integer	The recommendation type in integer format.	No
ShortDescription	Html	An abbreviated description of the recommendation.	Yes

RecommendationType

The number of recommendation types is extensible and the labels associated with the types in the Business Manager are configurable. RecommendationType is configured with three default values:

1 (cross-sell)
2 (up-sell)
3 (other)

If these types don’t satisfy your requirements, add new types or rename existing types.

To add additional attribute values, you can:

Configure them manually in Business Manager: Click App Launcher and then select Administration > Site Development > System Object Type > Recommendation.
Create them as part of a meta data import feed.

Analytics and Reporting for Explicit Recommendations

Salesforce B2C Commerce reports on recommendations using pipeline processing reports and system logs.

B2C Commerce provides pipeline processing data in Reports & Dashboards. To view the pipeline reports, click App Launcher and then select Merchant Tools > site > Analytics > Reports & Dashboards. Select the Technical Dashboard tab.

Because many implementations use pipelines to process recommendations, the Pipeline Usage and Pipeline Errors reports can provide useful information when testing and troubleshooting recommendations. Use the Pipeline Debugger.

System logs capture information related to API processing, data staging, and error handling. These logs can provide useful information when troubleshooting recommendation-related issues. To access system logs, click App Launcher and then select Administration > Site Development > Development Setup > WebDAV Log File section.

Developer Considerations for Product Recommendations

Developer work to define product recommendations includes modifying ISML templates, defining content slots, providing a unique ID, along with other customizations.

When implementing product recommendations, keep the following in mind:

Modify ISML templates to define content slots and display product recommendations.
When defining content slots for product recommendations, make sure you give the slot a unique ID and set the context to global.
If the content slot renders recommendations on product detail or category-landing pages, include the referring product ID or category ID as part of the context-object attribute.
Pass the context-object attribute a basket or dw.util.Collection of products. This option creates and uses recommendations based on selected products (up to 5), or all products in the basket.

This example <islot> tag shows how to define a slot for use on a product detail page:

1<isslot id="myslotid" context="global" context-object="${pdict.Product}"/>

This example shows how to define a slot for use on a category landing page:

1<isslot id="cat-banner" context="category" context-object="${pdict.ProductSearchResult.category}" />

For defined content slots on your storefront, make sure to create a page template to render the recommended products. If you already have a template that renders other types of product content slots, reuse these templates with some modification. When reusing a template, copy it to the /templates/default/slots/recommendation/ folder.

The following example provides a product template for showing product recommendations:

1<iscontent type="text/html" charset="UTF-8" compact="true"/>
2<iscomment> should not be cached, the tiles are cached individually.</iscomment>
3
4<isif condition="${slotcontent}">
5   <div class="product-listing product-listing-1x4">
6      <h2>${slotcontent.calloutMsg}</h2>
7
8      <ul class="search-result-items tiles-container">
9         <isloop items="${slotcontent.content}" var="product" begin="0" end="3">
10            <isobject object="${product}" view="recommendation">
11               <li class="grid-tile">
12                  <isinclude url="${URLUtils.url('Product-HitTile',
13                        'pid', product.ID,
14                        'showswatches', 'true',
15                        'showpricing', 'true',
16                        'showpromotion', 'true',
17                        'showrating', 'true')}"/>
18               </li>
19             </isobject>
20         </isloop>
21      </ul>
22   </div>
23</isif>

When developing slot-rendering templates for product recommendations, make sure that slot content caching is performed properly. Due to the dynamic nature of product recommendations, make sure not to cache the entire slot. If you cache the entire slot, every visitor experiences the same recommendations. Instead of caching the entire template, make sure that caching occurs when rendering individual product tiles.