NAV Navbar

Recco.js

Recco.js is a self-hosted JavaScript library which can be used to rapidly build an interactive, single-page-application user interface around the Luigi’s Box Recommender API.

You can integrate Luigi's Box Recommender by including the Recco.js script, setting configuration parameters and providing custom templates to customize the visual appearance.

Integration

By following this guide you will configure your site to use Recco.js to make request on your behalf to Luigi's Box Recommender API and display these recommendations back to your users. Since recommender is independent of what site is it included on you might use any site you have control over.

Example layout for the page

<html>
  <body>
    <!-- Header -->
    <!-- Product detail or other page content -->
    <div id="recommender-ui">
      <!-- Empty placeholder for recommender UI -->
    </div>
    <!-- Footer -->
  </body>
</html>

1. Prepare page for recommendations

Pick a page from your site that you would like to enrich with Luigi's Box Recommender – product pages, shopping carts or even home pages work best. Create an empty placeholder element where Recco.js will render recommender UI into. Note that if you pick element that is not empty, its contents will be replaced by the recommender UI.

For now we will use <div id="recommender-ui"></div>, however you can use any element or selector that fits you and your website.

<script type="text/x-template" id="..">
</script>
<script type="text/x-template" id="..">
</script>

<!-- Make sure that you define your templates before you initialize the Recco.js library -->
<script src="https://cdn.luigisbox.com/recco.js"></script>
<script>
  Luigis.Recomend({
    TrackerId: '2291-22343',
    Theme: 'luigis',
    Size: 5,
    Name: 'default',
    Type: 'basket_recommender'
  }, '#recommender-ui')
</script>

2. Setup Recco.js

Include the script and set configuration parameters. See the right column for an example.

Please note that:

  1. You must define your templates before you initialize Recco.js script. Templates are looked up when Recco.js first initializes and when they are not present in the page at that time, Recco.js will fall back to the default built-in templates.
  2. You must initialize the recommender by calling Luigis.Recommend. The initialization function takes 2 arguments: configuration object and CSS selector for the placeholder element where it will render the UI.
  3. You must define the initialization script (call to Luigis.Recommend) in the HTML after the placeholder element. The script expects to find the placeholder on initialization.

Without defining custom templates, you will get a very basic and unstyled recommender UI. You will most likely want to define custom templates where you can reuse your existing styles.

If you define the templates to match the HTML you are using today, there should be no extensive styling necessary.

Content Security Policy

If your website is using Content Security Policy, you need to add following rules to allow Luigi's Box Recco.js to work.

CSP directive Value
connect-src https://live.luigisbox.com
script-src https://cdn.luigisbox.com

Options reference

Luigis.Recommend accepts these arguments:

Option Comment  
TrackerIdREQUIRED Identifier of your site within Luigi's Box
Themeoptional Theme controls the visual style of the recommender UI. Recco.js currently supports 2 themes: 'default' and 'luigis'. We recommend that you start your integration with 'luigis' theme, and override template / style with CSS only what is necessary. See Theming for more details.
Sizeoptional Specifies how many results should the API return in each request (default: 10)
Type optional Unique identifier of a requested recommendation type. See Recommendation types for more details.
Name optional Name of the recommendations component. If you use multiple recommendation components on a single page they should be unique. Other values than "default" get appended to the template identifier, e.g. Name: "basket",... will make Recco.js look for template with selector #template-recommend-basket and #template-recommend-item-basket. (default: "default")
RecommenderClientId optional Arbitrary identifier which is returned in a response and might be used to distinguish between different recommendations. (default: same value as Name)
GetItemIds optional Function which returns a list of items to base the recommendation on. Depending on the type of recommendation and placement it might be a list of URLs of products in a shopping cart or category, list of URLs of products from previous purchases, current URL of a product user is exploring, etc. (defaults to empty list)
GetBlacklistedItemIds optional Function which returns a list of item URLs that must not be recommended, e.g. different product variants that are very similar to ones returned by GetItemids or items which cannot be bought at the moment. (defaults to empty list)
Locale optional String, indicating a locale identifier which will setup the default translations and price format. See Localisation for more information.
Translations optional Object, including translation keys and translation themselves. See Localisation for more information.
PriceFilter optional Object, including configuration for price formatting. See Price format for more information.

Luigis.Recommend also accepts a mandatory CSS selector for element where Luigi's Box recommender component should be rendered, e.g. #recommender-ui.

Templates

Luigi's Box Recco.js is using templates to render list of recommendations. While we include all templates in the default Recco.js distribution, they are not styled. Usually, you will want to define your custom template which matches the styling of your site. Templates are using Vue.js template syntax under the hood.

You should define these templates directly in your HTML code. Each template must be defined in its own <script type="text/x-template> tag. Templates are looked up by their id attribute — make sure to not change it. You don't have to redefine every template, only those that you will actually use.

Main template

Example of main recommendations template

<script type="text/x-template" id="template-recommend">
    <div>
        {{ $t('recommend.title', { name: name }) }}
        <recommend-item
            v-for="item in items"
            :key="name.concat('-').concat(item.url)"
            :item="item"
        ></recommend-item>
    </div>
</script>

This is the root template used for rendering recommendations layout. Use this template to define how your recommendation UI should look. You can reference a <recommend-item> component which renders individual recommended items.

Recommended item component

Default recommend-item component definition

<script type="text/x-template" id="template-recommend-item">
    <div>
        <strong class="lb-default">Default Recommend Item</strong>
        <small>{{ item.url }}</small>
    </div>
</script>

Referenced as <recommend-item>.

Used for generating single recommended item. The default definition will render URL of each recommended item in a separate div with just the product URL. Override this template to render items in a custom structure, such as <ul> list or if you would like to display more details.

Recipes

Theming

Recco.js comes with 2 themes which control the visual style of the recommender UI.

  1. luigis - which will give you a nicely styled list of recommendations. Use this theme, unless you have special requirements and plan to implement the recommender UI yourself from scratch.
  2. default - which is a barebone visual style, which only provides a very basic and unstyled UI. If you plan on implementing all templates by yourself, use this template.

Localisation

Localisation is controlled by 2 parameters: Translations which contains the translation keys and translated strings and PriceFilter, which controls the price format. There is also a 3rd parameter — Locale which just sets up built-in translations and price formats.

When localising the Recommender UI, we recommend that you configure Locale to load the defaults and then adjust translations or price format as necessary.

The locales supported out of the box are:

To load the default locale settings, use the country code, e.g. Locale: 'sk'.

Translations

Default English translations

{
    "recommend": {
        "title": "Recommended by Luigisbox - {name}"
    },
    "recommendItem": {
        "actionButton": "Detail",
        "availability": {
            "0": "Unavailable"
        }
    }
}

Translations are configured as a JavaScript object (JSON). See the defaults for English in the column with code examples. Note that the object that you pass to Translations is merged with the built-in translations. You can add new translations, you can override built-in translations, but you cannot delete a translation.

The Translations object must include the locales as the top-level keys. Note that you don't have to define the translation for all supported locales, but only for those that you care about.

For example, to override translation for action button in a product tile, set Translations: {"en": {"recommendItem": {"actionButton": "See product details"}}}.

If necessary, you can access the translation mechanism by calling a $t function from within the Recco.js templates. Pass it the translation key as an argument and additional parameters, e.g. {{ $t('recommend.title', {name: 'Example'}) }}.

You can also use $tc function which provides pluralization support. If you define translations like Translations: {"en": {"recommend": {"title": "0 recommendations | 1 recommendation | {hitsCount} recommendations"}}} you can use the pluralization function {{ $tc('recommend.title', hitsCount, {hitsCount}) }} which would output the translation based on hitsCount variable.

For more details see Vue I18n documentation.

Price format

Price format is controlled by a price filter, which is automatically called from within the default templates, such as {{ item.attributes.price_amount | price }}.

You can control the price filter options by setting PriceFilter parameter in the configuration options.

PriceFilter: {"decimals": 0, "prefixed": false, "symbol": "CZK"}
option description
decimals Specifies rounding precision
prefixed Boolean, specifies if the price symbol should be displayed before or after the price ($42 or 42$)
symbol The currency symbol