Implementing Nosto's product recommendations in a MyCashflow theme

This article explains how to implement Nosto's product recommendations in a MyCashflow theme.

Introduction

The Nosto extension has been deprecated.

We don't recommend activating the service in your online store. The current service settings are still fully operational, though.

Two things are required to implement Nosto in a store theme:

installing Nosto's JavaScript library and data collection tools and
printing recommendation lists in selected locations of the theme.

In MyCashflow's old default theme, there is a separate branch for Nosto, where almost all lists that print product recommendations are replaced with corresponding Nosto lists and where you can find the scripts mentioned in this article. You can download our default theme with Nosto here (direct download link).

Nosto is not included in our new default theme by default.

If you only need the required scripts for your theme, you can find them here:

Installing Nosto scripts and data collection tools

For Nosto to generate personalized product recommendations, it needs to collect information about your customers' browsing behavior. To do this, you need to install the Nosto JavaScript library in your online store.

You can use the {Extensions} tag, which prints codes required by other extensions too, to print Nosto's scripts for collecting data and returning product recommendations in your store. In many themes, the tag is already in place, and no action is required.

{Extensions (for: 'head')} prints Nosto's JavaScript library and MyCashflow support scripts to convert the products returned by Nosto to Interface markup. The tag must be located in the HTML source code between the <head></ head> tags. Alternatively, you can use the {NostoScript} tag to print only those scripts that are required by Nosto.

The {Extensions (for: 'body')} tag prints page metadata for Nosto. This tag must be located in the HTML source code immediately after the opening <body> tag. Alternatively, you can use the {NostoTag} tag to print only Nosto metadata.

Adding Nosto product lists to the store

Nosto's recommendation lists are printed with the {NostoProducts} tag. In the tag's slot attribute, include information about the type of product recommendation defined in Nosto's admin panel that you want to use. For example, {NostoProducts(slot: 'nosto-frontpage-3')} would return the products from the nosto-frontpage-3 slot.

The tag differs from other product list tags in that the tag does not directly return products' HTML markup, but the following HTML element:

<div class="nosto_element" id="nosto-frontpage-3" data-nosto-params="limit=15&type=normal"></div>

The sample markup has been printed with the following tag markup:

{NostoProducts(
    slot: 'nosto-frontpage-3',
    limit: 15,
    type: 'normal'
)}

All regular attributes of the {Products} tag also work with the {NostoProducts} tag.

Because the {NostoProducts} tag does not directly return the products' HTML markup, in order to print them, you need to add the mcf.nosto.js jQuery plugin that receives the products returned by Nosto and prints the HTML markup compatible with the {NostoProducts} attributes on the page e.g. inside the <div> element.

The mcf.nosto.js plugin

The Nosto plugin is required for the {NostoProducts} tag to work. The plugin converts Nosto's product recommendations into markup that is compatible with the Products tag. The script is dependent on the jQuery library.

The {NostoProducts} tag and the mcf.nosto.js plugin cooperate in the following way:

The tag prints the element to which Nosto's product recommendations are loaded.
The plugin requests the {Products} tag's markup from Interface.
The contents of the <div> element are replaced with the requested output of the {Products} tag.
The optional callback function is performed (error or success depending on the result of the call).

Here is the most straightforward way to enable the mcf.nosto.js plugin:

$('.nosto_element').mcfNosto();

Do not change the .nosto_element class selector because the class name in question comes from the {NostoProducts} tag.

Kuva 1. Callback functions

As Nosto's product recommendations are loaded asynchronously, it is important for the plugin to offer the ability to run JavaScript on downloaded products. It has been accomplished through callback functions. Callback functions are useful e.g. in case of product carousels that cannot be initialized until Nosto's product recommendations have been loaded.

The plugin can be given two callback functions in the initialization stage – error and success:

$('.nosto_element').mcfNosto({
    success: function() {
        // The Nosto element is available via the this.$elem variable
        // Example of product carousel initialization for Nosto's products:

        var $crossSaleScroller = this.$elem.find('.CrossSaleScroller');
        if ($crossSaleScroller.length) {
            $crossSaleScroller.cycle();
        }
    },

    // The error function is called if Nosto does not return
    //product recommendations for that slot or the Interface call fails.
    error: function(msg) {
        // The msg variable contains an error message reported by the plugin.
        if (typeof console === 'object') { console.log(msg); }
    }
});

Using multiple Nosto accounts in the same online store

It is possible to choose or create a new Nosto account for each version of the store in the extension's settings.

If the {Extensions} tags are used to print the scripts, using different accounts in different versions is enabled automatically. Otherwise, the {NostoScript} tag must be used with the Nosto account's username indicated in the account attribute, e.g. {NostoScript(account: 'mcf-kauppa-fi')}.

In the theme, place the {NostoScript} tag before the {Extensions(for: 'head')} tag so that the account change is noted before the extension information is printed.

Why doesn't MyCashflow use Nosto's templates?

Because we believe that the Interface markup is a better tool for designers who want to integrate Nosto's product recommendations into a ready layout theme of their online stores.

Normally, Nosto would also return with product recommendations their HTML markup, styles and JavaScript codes that should be edited in Nosto's admin panel. In such case, a designer who is working on a MyCashflow store would have to learn a new tool and Nosto's syntax in order to edit the output so that it suits the store's layout.

Instead, we decided to create a product recommendation template for MyCashflow stores' Nosto accounts; the template contains nothing other but IDs of the products that are returned by Nosto's product recommendation logics based on user browsing data. In the MyCashflow store theme, such ID list can be submitted to the {Products} tag that will print the products accordingly. In this way, the designer doesn't have to learn Nosto tools and can relay on Interface markup to print Nosto's product recommendations.

Another advantage of this approach is that it allows for filtering Nosto's product recommendations in the store theme. For example, if you wanted to show recommendations based on others' browsing history including only discount products, you could do it with the following markup:

{NostoProducts(
    slot: 'nosto-navigation-2',
    filters: 'discounted'
)}

The {NostoProducts} tag uses mainly the same attributes as the {Products} tag, so you apply the general product list filters to it.

THEME GUIDE