When you need to reload the recommendations on the page, you can use this call to reload the recommendations:

The call accepts an optional parameter, but in most cases, that parameter is not required. Add the optional parameter only if the reason to reload new recommendations is the result of clicking an existing recommendation and some new product was loaded. A typical use case where this would be the case is when a recommendation has a quick view button that dynamically loads a new product into a CSS overlay with ajax.

Conditional loading

By default, Nosto loads the recommendations as soon as the site’s DOM is loaded. In some use cases, Nosto needs to be loaded manually. This is done by disabling autoload directly after the nosto script:

and conditionally later to trigger loading

This pattern should not be used to load Nosto faster, but as a pattern to conditionally load Nosto. If api.load() is called before this site's DOM is loaded tagging data won't be fully available and Nosto will not function correctly.

In most implementations, there isn't any need to use the Nosto JavaScript API and the regular tagging implementation approach will suffice.

Typically calling the API should be approached only after the normal tagging implementation has been done and now needs to be extended with something that doesn’t come out of the box. The JavaScript API is commonly used to support dynamic functionality i.e. without a page reload. For example, showing recommendations in a product quick view.

If you are working on a Single-Page App (SPA) or a Progressive Web Application (PWA) you most likely want to use Session API. Also, please note that you can not use both, Session API and JS API on a same page or application.

Prerequisites

JavaScript API works only in on-site context. Using the API does not require authentication but requires that Nosto embed script is included.

Nosto embed script needs to be recent enough. The easiest way to check that you are using a recent version enough is to view your site’s HTML source and make sure it includes the text nostojs.init. In case that is there you are using the version that supports the Nosto Javascript API.

If you are using Nosto with a async script tag (AKA Direct Include), then you must add a javascript stub as an inline script block before you call the Nosto Javascript API (see the Javascript examples). You do not need to call nostojs.init() when using Direct Include.

(function() {
 var name="nostojs";
 window[name]=window[name]||function(cb){(window[name].q=window[name].q||[]).push(cb);};
})();

Using the stub ensures that your code will be executed correctly even if you call the Nosto JS API before the Nosto script has loaded.

Nosto is initialized automatically once the script has loaded. Unlike the legacy script, you do not need to manually initialize Nosto.

Disabling Autoloading

In the event that you would like to initialize Nosto but not have it automatically load the recommendations, you can set setAutoLoad to false.

  nostojs(api => api.setAutoLoad(false));

Also see: Setting up for how to first include the script stub that allows API usage in this manner.

Note: You will need to manually load the recommendations when the autoloading is disabled. A recommendation request needs to be sent in order to track user events. So, if autoloading is disabled and you wish to track an order or cart changes, you need to send a recommendation request even if you don't wish to display recommendations on the page.

In this article, you will learn to use certain tags and fields to dynamically filter and facet your recommendation results.

You can use any combination of the different filtering mechanisms outlined below. For example, you can use category and the tag filtering to constrain the recommendation results.

Note: In order to leverage dynamic filtering please read our guide on configuring the filtering behaviour.

All category pages already leverage dynamic filtering. As documented in our guide to tagging categories, the nosto_category tagging constraints Nosto to show recommendations from only the current category.

Tagging the current category is often for most retailers to add personalization to the category pages. If your store uses faceting and you would like Nosto to respect the faceting constraints, you may need to use either the attribute or tag filtering mechanisms to achieve the desired result.

Filtering by categories

You can filter by categories to narrow down the recommendation results to only show products from the specified category or categories. If multiple categories are specified, the products must be in each of those categories.

<div class="nosto_category" style="display:none">/Men's/Shirts</div>

You can even use multiple

<div class="nosto_category" style="display:none">/Men's/Shirts</div>
<div class="nosto_category" style="display:none">/Men's/Sale</div>

Note: Remember to tag the categories exactly as they are tagged in your product pages. If you've omitted the leading /Home from your category tagging on the product pages, you'll need to tag them in a similar format here.

Filtering by tags

You can filter by tags to narrow down the recommendation results to only show products containing the specified tag or tags. If multiple tags are specified, the products must contain all the specified tags.

<div class="nosto_tag" style="display:none">colourful</div>

You can even use multiple

<div class="nosto_tag" style="display:none">colourful</div>
<div class="nosto_tag" style="display:none">shiny</div>

Filtering by attributes

You can filter by attributes to narrow down the recommendation results to only show products containing the specified attributes. If multiple attributes are specified, the products must contain all the attributes.

<div class="nosto_custom_field" style="display:none">gender:male</div>

You can even use multiple

<div class="nosto_custom_field" style="display:none">gender:male</div>
<div class="nosto_custom_field" style="display:none">material:cotton</div>

These colon separated values are then parsed into an object with format { "key1":"value1,value2", "key2":"value1" }.

texts.keyValueTexts(nodes)

The above method will receive references to all the "nosto_custom_field" elements. It extracts the colon separated strings and parses them to an object. For e.g. the above gender and material custom fields will be parsed to

{
  "gender": "male",
  "material": "cotton"
}

Dynamically reloading

If you want to refresh the recommendations with new facet constraints, the simplest way would be to update the value of the filters in the page and then reload the recommendations.

The following example illustrates a simple way of modifying the current category tagging and then using the JS API to reload the recommendations.

document.querySelector('.nosto_category').innerText = '/Shoes'

nostojs(api => {
  api.loadRecommendations();
});

When you need to explicitly send an event to Nosto to tell it that the user has viewed a certain product, you must do so manually. A need for something like this arises when your website has a quick-view function on the category or search pages that enables the customer to preview the product in an overlay without actually navigating to the product page.

nostojs(api => {
  api.createRecommendationRequest()
    .setProducts([{product_id: 'product-id-101'}])
    .load();
});

Note: The example above creates a new request, adds view product event for product-id-101 and sends the event to Nosto. Since the request did not specify any recommendation slots, this request only submits view event to Nosto.

You can either create an empty request as in the above example and add only the wanted parts to it, or you can create a request based on the tagging on the page by using the includeTagging field and then modify it. Here is an example that creates a request using the tagging on the page and then overrides the current tag to be custom colour to update the recommendation with id productpage-nosto-2 to show only products with the same colour:

nostojs(api => {
  api.createRecommendationRequest({includeTagging:true})
    .setCurrentTags(["color:red"])
    .setElements(["productpage-nosto-2"])
    .load()
    .then(response => {
      console.log(response);
    });
});

In addition to the filtering by product tags, you're also able to filter using product attributes. Here is an example that creates a request using the tagging on the page and then overrides the current tag to be custom colour red, to update the recommendation with id productpage-nosto-3 and to show only cotton material products for men of the same colour (red):

nostojs(api => {
  api.createRecommendationRequest({includeTagging:true})
    .setCurrentTags(["color:red"])
    .addCurrentCustomFields({gender: "male", material: "cotton"})
    .setElements(["productpage-nosto-3"])
    .load()
    .then(response => {
      console.log(response);
    });

In many cases leveraging the existing tagging on the page and then overriding the specific parts is simpler and more robust.

Attribution for recommended Products

In case the request is built completely manually, it needs to include also the attribution information for click tracking. Below is an example which shows how that can be done for product views that result from clicking on a Nosto recommendation slot.

In the event that the product was viewed due to a click on a Nosto recommendation slot, you must send an additional parameter that denotes the identifier of the recommendation slot that was clicked. If this is done inside of recommendation template identifier of recommendation slot can be get from property $!product.attributionKey

nostojs(api => {
   var request = api.createRecommendationRequest()
     .setProducts([{product_id: 'product-id-101'}], 'recommendation-id')
     .load();
});

Note: Failure to do will result in incorrect attribution statistics.

Sending Product Variant-view Events

Optional event that can be sent to signal that a specific product variant (SKU in Nosto terms) is being viewed. Typical use case for sending this event would be from product detail page when the user selects a product variant, such as some specific color and/or size. The recommendations can then be configured to update and give preference for products that have similar variants available. For example "Other products also available in the same size".

nostojs(api => {
  api.createRecommendationRequest({includeTagging:true})
    .setProducts([{product_id: '6961338417345', selected_sku_id: '40822930473153'}])
    .load()
    .then(response => {
      console.log(response);
    });
});

The JS API can be used to register callbacks to hook into the recommendation events. To register a listener for a callback, use api.listen(callbackId, callbackFunction) function.

Post Render Callback

Called when Nosto has responded and finished recommendation placement.

nostojs(api => {
  api.listen('postrender', event => {
    console.log(event.filledElements);
    console.log(event.unFilledElements); 
  });
});

Fields

Pre Render Callback

Called when Nosto has responded but not yet rendered content. The event contains information about the visitor's preferences.

nostojs(api => {  
  api.listen('prerender', event => {    
    console.log(event);
  });
});

Fields

You can use the JS API to list all the popup campaigns. This may be handy in situations when you would like to fetch all campaigns and iterate them to decide whether they should be shown or not.

Fields

You can open up a Nosto behavioral pop-up by calling the api.openPopup() function. The first argument of the function is the ID of the popup campaign whose pop-up you want to show. The pop-up campaigns, including the pop-up templates themselves, are created in the Nosto Administration UI

Please note that some campaigns have active trigger types and can be opened automatically. If you want to use only the api.openPopup() call to open pop-ups, please create the respective campaigns using the JavaScript API pop-up trigger type.

You can also give a second, optional argument to the api.openPopup() function. The second argument is an object with the following fields:

Parameters

Usually adding an Add to cart button directly into the recommendation which lists multiple products is fairly straightforward, the website just needs to have an appropriate javascript function to do the operation. Nosto provides ready-made functions for multiple platforms so check the Nosto documentation specific to your e-commerce platform or if needed look into your e-commerce platform's documentation and support on how to create such a function.

Once the Add to cart button is pressed it should call that function to add the products to the cart, but it should also additionally let Nosto know that the button was pressed so Nosto can track the sales from the recommendation. When using the JS API this attribution can be done with the recommendedProductsAddedToCart-function as follows:

⚠️ The api call is only for informing Nosto about the attribution (that the product was added from the recommendation), normal cart tagging should be used to tell Nosto the user’s cart contents.

The JS API can be used to register callbacks to hook into the popup events. To register listener to a callback, use api.listen(callbackId, callbackFunction) function.

Email Given Callback

Whenever customer has input their email address into a Nosto behavioral pop-up that asked whether they want to subscribe to an email newsletter.

Fields

Popup Opened Callback

Fields

Popup Ribbon Callback

The customer can minimize a Nosto behavioral pop-up into a ribbon to be shown at the edge of the viewport. The pop-up is also changed to be shown in its minimized ribbon form after a page load is done after a pop-up has been shown.

This callback will be called whenever the ribbon is rendered onto screen after a page load.

Fields

Popup Minimised Callback

The customer can minimize a Nosto behavioral pop-up into a ribbon to be shown at the edge of the viewport. This callback will be called when the customer clicks the minimize button on the pop-up.

Fields

Popup Maximised Callback

The customer can minimize a Nosto behavioral pop-up into a ribbon to be shown at the edge of the viewport. When they click on this ribbon, the pop-up will be maximized again to be shown in full size. This callback will be called when the customer clicks the ribbon to maximize the pop-up.

Fields

Popup Closed Callback

The customer can click a “close permanently” button or link in a Nosto behavioral pop-up to dismiss the pop-up permanently. This callback is called when the customer clicks on that button or link.

Fields

Coupon Given Callback

The callback will be called when a customer clicks a button inside a Nosto behavioral pop-up to get their discount coupon code.

Fields

Cart Abandonment Callback

The callback will be called when a customer clicks a button inside a Nosto abandoned cart pop-up to get an abandoned cart email.

Fields

In the event that you are using Nosto's Onsite Popups, you can leverage the JS API to build complex interactions with the popups.

See the following articles on how to use the JS API to interact with popups:

You can use the JS API to conditionally enable or disable a popup.

Enabling a Popup

The following snippet enabled the specified popup.

Parameters

Disabling a Popup

The following snippet disables the specified popup.

Parameters

Use api.customer() function to send information about the current customer to Nosto. After the information is sent, current visit is updated with latest details.

Typical situation when manual update is needed if your site handles login with AJAX compared to regular implementation where login requires a page load and the following page includes customer tagging.

nostojs(api => {
  api.customer({
    email: "jane.doe@example.com",
    first_name: "Jane",
    last_name: "Doe",
    marketing_permission: true,
    customer_reference: "5e3d4a9c-cf58-11ea-87d0-0242ac130003"
  })
});

In this article, you will learn how to collect email addresses from other sources. If you have implemented the customer tagging, Nosto will automatically collect the information for logged-in users. For all other scenarios, you will need to use our Javascript API to push the customer information to us:

Collecting email addresses from a form field

If your website has a form field that accepts email address, you can collect customer information using our JS API. A more simplified way would be to add the class nosto_email_capture to any email field on the page whose addresses need to be captured. Having done that, include the following snippet into your site.

The jQuery based script below binds every input field with the class nosto_email_capture and submits the collected information to Nosto when the parent form is submitted.

jQuery("form input.nosto_email_capture").each((idx, input) => {
    if (!input.form) {
        return;
    }
    input.form.onsubmit = event => {
        var email = input.value;
        if (email) {
            // Push customer information to current visit
            nostojs(api => {
                console.log("Collecting email " + email);
                api.customer({email: email});
            });
        } else {
            console.log("No email specified");
        }
    }
});

While Nosto leverages customer attributes and behavioral signals to automatically segment users, there may be scenarios where you may want to explicitly segment users. You can do so by affixing a segment-code to the current user and then leverage Nosto's segmentation tool to segment users with that specified attribute.

nostojs(api => {
  api.addSegmentCodeToVisit('women');
});

The example above does not trigger a reload of all the placements. If you would like to reload all onsite content to reflect the new segment, you must explicitly reload it.

nostojs(api => {
  api.loadRecommendations();
});

Once you have done so, read our guide on segmenting users via custom events.

The example below illustrates how to fetch the fresh cart content over CORS, leverage that to render the cart tagging and then use the API to sent that information to Nosto.

function lineItemToHtml(item) {
  return `
    <div class="line_item">
      <span class="product_id">${item.product_id}</span>
      <span class="sku_id">${item.sku_id}</span>
      <span class="quantity">${item.quantity}</span>
      <span class="name">${item.name}</span>
      <span class="unit_price">${item.unit_price}</span>
      <span class="price_currency_code">${item.currency}</span>
    </div>
  `
}

function cartToHtml(cart) {
  return `
    <div class="nosto_cart" style="display:none">
      ${cart.items.map((item) => lineItemToHtml(item))}
    </div>
  `
}

/**
 * This example fetches cart content from an external endpoint, uses 
 * that information to render the cart-tagging and then reloads the 
 * recommendations if needed.
 *
 * This snippet is written under the assumption that the data returned
 * by the endpoint resembles the following
 * {
 *   items: [
 *     product_id: "product_id",
 *     sku_id: "sku_id",
 *     quantity: "quantity",
 *     name: "name",
 *     unit_price: "unit_price",
 *     currency: "currency"
 *   ]
 * }
 */
export default function() {
  nostojs(api => {
    fetch("https://www.example.com/cart")
      .then(response => {
        const tagging = cartToHtml(response.json())

        document.querySelectorAll('.nosto_cart')
          .forEach(element => element.remove());
        document.body.append(tagging)

        api.resendCartTagging();
      })
  })
}