This example shows you how to create a recommendation for products that visitors typically purchase together. The example uses a recommendation configuration to generate the recommendation data. The example covers the entire development workflow from creating and testing the configuration to creating the modification that displays the recommendation.
In this example, you:
- Create a recommendation configuration for the top 10 products purchased together with a given product in the past 30 days.
- Create a customizable template for a product recommendation slider. The template uses the Recommendations API for populating the slider with recommendation data generated from the recommendation configuration.
- Create a modification and associated placement for displaying the recommendation on product pages. The modification uses the recommendation slider template for its content.
You create all the components of the recommendation in the Frosmo Control Panel.
The following figure shows an example of the final recommendation on a product page.
Figure: Product page with a recommendation for products purchased together (click to enlarge)
To create the recommendation:
- Create and test the recommendation configuration.
- Create the recommendation slider template.
- Create the modification and associated placement for displaying the recommendation on product pages.
Creating and testing the recommendation configuration
The recommendation configuration returns up to 10 other products most often purchased together with a given product in the past 30 days.
Creating the recommendation configuration
To create the recommendation configuration:
- In the Frosmo Control Panel, in the sidebar, select More > Recommendations.
- Select the Configurations tab.
- Click Create recommendation configuration.
In the code editor, replace the default recommendation configuration with the following code.
Note the following settings:
bundle_convertedis the recommendation type for products purchased together.
1dmeans that the recommendation data is regenerated once per day based on the latest usage data collected from the site.
720means that the recommendation data is always generated from the last 720 hours (30 days) of usage data collected from the site (in this case, product and transaction data).
10is the maximum number of products to include in the recommendation data. This is the number of other products to recommend for a given product. If customers have purchased more than 10 products together, the recommendation returns the 10 most purchased products.
productinstructs the platform to return the full product data for each recommended product. The alternative is to return the raw recommendation data for each product, but then you'd have to separately retrieve the product data to display in the modification.
params: Product recommendations whose type is
bundle_convertedrequire a single request parameter: the target product attribute against which the recommendation is generated. This example recommends products based on a given product, so the parameter must identify that product. Hence, the product ID, which is here named
product_attrsarray tells the platform how to map the request parameters defined in
paramsto product attributes in product data. This example defines a single request parameter,
productId, which maps to the
idattribute of products.
For more information about the settings, see the recommendation configuration reference.
- Click Save. The platform queues the recommendation configuration for data generation.
- To return to the recommendation configurations list, click Cancel.
You have created the recommendation configuration. Once the recommendation configuration status changes to Success, the recommendation data has been successfully generated, and you can retrieve and review the data.
Figure: Recommendation data has been successfully generated
Testing the recommendation configuration
Testing the recommendation configuration means reviewing the generated recommendation data to ensure that the data meets your expectations.
To test the recommendation configuration:
In the Control Panel, in the recommendation configurations list, find the configuration, click the quick menu button for the configuration, and select Preview.
The full recommendation data opens in a new tab. The data is retrieved with the Recommendations API.
Enter a product ID in the request URL, so that you can view the recommendation data for a specific product.
If the product has been purchased together with other products by one or more visitors in the past 30 days, the page displays the corresponding recommendation data in the JSON format. If the product has not been purchased together with other products, or if the product ID is invalid, the page displays an error.
If you need to find out what products IDs are available on your site, make a Graniitti API GET request to
/sites/<site_id>/products, and check the
product_idvalues in the response data.
You have tested the recommendation configuration. You can now use its recommendation data in a modification.
Creating the recommendation slider template
The template creates a simple product recommendation slider. The template provides variation content options for customizing the title and the number of displayed products for the slider. The template uses content prerendering to fetch and process the recommendation data before building and rendering the final slider element.
Figure: Customizable parts of the recommendation slider (click to enlarge)
To create the recommendation slider template:
- In the Control Panel, in the sidebar, select Modifications.
- Select the Templates tab.
- Click Create template.
Define the following settings:
- Name: Enter "Product recommendation slider".
- Export content: Leave this field to Automatic.
- Minified: Leave this to Enabled.
Content: Enter the following content for the template.
The content defines the HTML and CSS code for the recommendation slider. The content includes multiple Mustache tags, which need to be replaced with specific values in the final rendered content.
Feel free to edit the content to adapt the slider to your site's layout and style.
Content prerenderer: Enter the following content prerenderer for the template.
The content prerenderer:
- Fetches the recommendation data by calling the Recommendations API.
- Builds the final content options with which to render the template content. These are the values for the Mustache tags in the content. The values include the recommendation title, which comes from the
titlecontent option set in the modification variation, and the final set of recommended products, which the prerenderer crops from the recommendation data based on the
numberOfProductscontent option set in the modification variation.
- Triggers the template content to be rendered with the final content options.
In the code, replace the values of the
originvariables with values appropriate to your Frosmo Platform instance and site. To get the values, see Graniitti API: Requests and Getting your site origin.
Content options schema: Enter the following content options schema for the template.
The schema describes the following content options, which must be set in the content options UI of the modification variation:
- Recommendation title (
- Number of products to recommend (
The template uses both content options to create the final recommendation slider element. While the template content uses
titleas is, the content prerenderer uses
numberOfProductsto produce the final set of recommended products with whose data the recommendation slider gets populated.
- Recommendation title (
Content options UI schema: To further customize the content options UI, enter the following content options UI schema for the template.
The UI schema defines a placeholder text for the Recommendation title field of the content options UI.
The following figure shows the complete template in the Control Panel. Click the figure to view a larger version.
For more information about the settings, see Creating and editing a template.
Use the content options UI preview at the bottom of the editor to test that the content options schema and content options UI schema are correctly defined.
The preview is fully interactive, so any changes you make to the schemas are automatically reflected in the preview. You can also set the content options in the preview as you would in the actual content options UI, and you can see a preview of the JSON object generated based on the set values.
The following figure shows the content options UI preview for template.
- Click Save.
You have created the template. You can now use the template in a modification to display the template content.
Displaying the recommendation
When a visitor navigates to a product page, they see a recommendation for up to 10 other products that visitors have typically purchased together with the current product.
For example purposes, let's assume that a product page can be identified by
/product/ in the page URL, and that the main product details are contained in a
<div class="product-info"> element. You'll place the recommendation slider below the main product details on every product page.
Figure: Recommendation slider below the main product details on a product page (click to enlarge)
The URL scheme, content layout, and source code structure of a product page on your site almost certainly differ from the above. You could also use a trigger instead of a URL matcher to identify product pages, and you might want to place the recommendation slider differently.
To display the recommendation:
Creating the recommendation slider placement
To create the recommendation slider placement:
- In the Control Panel, on the Modifications page, select the Placements tab.
- Click Create placement.
Define the following settings:
- Name: Enter "Product page - Recommendation".
- Page type: Select Product.
- Target element: Select CSS selector, and enter "div.product-info" as the selector name.
- Display method: Select After element.
- URL matcher: Click Add new rule. Since only product page URLs contain
/product/in their path, define the following rule: Page path contains /product/. This means that the placement is valid for a page only when the page URL path contains "/product/".
The target element, display method, and URL matcher together place the modification below the main product details on every product page.
For more information about the settings, see Creating and editing a placement.
- Click Save.
You have created the placement. You can now use the placement in a modification.
Creating the recommendation slider modification
To create and activate the recommendation slider modification:
- In the Control Panel, on the Modifications page, select the Overview tab.
- Click Create modification.
Enter "Product page - Recommendation - Purchased together" as the modification name, select Personalization as the modification case, and click Create.
You could also select another case, but since this modification needs only the one variation, Personalization is the natural choice here.
For more information about the settings, see Creating and editing a modification.
Select the placement for the modification:
In the Basic settings view, in the Placement section, click Select placement.
Select the placement you created for the recommendation slider.
- Click Save.
For more information about the settings, see Defining the placement for a modification.
Define the content for the modification:
In the Basic settings view, in the Content section, click the variation name.
- In the Variation settings section, click Select type.
In the Content templates list, select the template you created for the recommendation slider, and click Select.
In the Content options section, define the content options. You must define both Recommendation title and Number of products to recommend. The following figure shows one example of setting the options.
- At the bottom of the view, click Save.
Back in the Content section, click the quick menu button for the variation, and select Activate.
- If you want to disable the comparison group for the modification, click the quick menu button for the group, and select Deactivate.
For more information about the settings, see Defining the content for a modification.
- Activate the modification:
- At the bottom of the Basic settings view, click Activate.
- To confirm, click Activate.
You have created and activated the modification. The recommendation is now live, and you're done with this example!