We are glad to have you as a partner and want to help you get running with Nosto as soon as possible while making it as easy as possible for you.
Our material consists of a general introduction to how Nosto works, additional in-depth information and examples for every product with its possible implementation methods as well as comprehensive API references.
We appreciate your professionalism and understanding that we can't document every single use case. We are confident you'll find everything needed to deliver on your requirements. Custom cases need custom solutions and we'll guide you in the right direction.
If you ever feel stuck, something is confusing or misleading, please contact us so we can a) support you and b) update our information.
Nosto offers different APIs to use and they all mostly offer the same functionality (in some cases you’ll face a classical trade-off battle). That’s why it’s important to not just look at what you want to achieve, but what setup you currently have (and what your client needs).
We want to make the implementation as easy and clean for you as possible. We don’t want you to bloat up your code or you to do unnecessary things.
Therefore, please take a few minutes and write down the answers to the following questions so we can prevent future headaches (and save a lot of time and money):
Is your client’s site running on a major eCommerce platform like Magento 2, Shopify, Shopware, BigCommerce, Prestashop or Salesforce?
Have you decoupled the frontend from the backend/are you running a headless frontend? (incl. Magento 2 Hyvä, React, Next.js or Shopify Hydrogen)
Is the frontend a single-page-application (SPA) or a progressive-web-app (PWA) where the URL never changes when a user browses the site?
Does your client have an international/localized setup with multiple currencies and/or languages?
Does your client have multiple customer groups?
We will ask you for these answers in our kickoff meeting and will craft the mutual project plan accordingly.
Fundamentally, Nosto needs a replica of the client's product catalog with price and currency information, parent/child relations, categories, custom fields, tags, stock/inventory information, etc..
To achieve the onsite functionalities, Nosto must be able to do these things:
Know on which page the users are.
Know what data is on a page (what product, what category, …).
Know specific things about the current user (on all pages):
Shopping cart content
Name and email (if logged in)
Know about certain events like impressions and clicks.
Write content to the page, either from the client- or server side.
Access your frontend: , you must provide valid product URLs and product images.
Nosto replicates an eCommerce site’s product catalog (one account per domain/language) as the foundation for all Nosto modules. You might need to adjust the product data structure, so please let us know about your parent/child relationships, customer groups (pricing and visibility) and how you handle translations and multiple currencies (fixed prices or exchange rates).
Nosto then does two basic things onsite:
Profile creation: Track what a user is doing on an eCommerce site (which pages (landing page, product page, category page, …) shoppers look at and what they buy).
This data is sent to the Nosto backend so we can understand and present insights to the client in our dashboard.
Content personalization: Change the content on an eCommerce site per user depending on the data we have collected and which campaigns have been set up by the client.
"Content" is a broad term and ranges:
from a hero/banner image on a home, landing, category or product page
to product recommendations ("You might also like") on any page type (or even in the mini-cart or search overlay)
to conversion rate optimized, personalized category pages and SERPs which replace the native platform functionality.
Nosto has several apps/plugins for common platforms like Shopify, Shopware, Magento, ... that give you a head start. Please review the platform-specific documentation at the bottom of this page. The feature set (product and order sync, adding the script and page tagging, ...) can vary and might need to be extended for custom requirements.
It is tempting to skim the headings of a documentation (we feel you and know you want to get back to coding asap). We also understand that you want to make sure you can cover all the complexity for your client and site.
From our experience, there is always added frustration and costs due to several added feedback loops when we take shortcuts in the beginning. You and your client will get the most out of your time and the Nosto platform when you:
Set aside one hour to read this guide and write down all questions or concerns you might have.
Use our onboarding team to consult and assist you with best practices. We are there to help you with troubleshooting.
Focus on the basics first before addressing the complex use cases (although we know they are more fun).
Use the product as it is intended. This is the most common pitfall: After hours and hours of complex programming it often turns out there already is a functionality inside the platform which is configured with only a few clicks.
Don't just copy & paste the code examples. Yes, it happens. To improve readability, our examples give you an overview with only the most relevant data/parameters. We don't want to clutter your mind, so please refer to the API references for an extensive overview.
We are happy to with any question regarding the details and are confident you will be able to solve 90% of your questions with this guide.
Pro Tip: Let us review your project plan/milestones before you get started.
We can't stress this enough: When the basics are missing, the more advanced features won't work as intended and you will become very frustrated.
Therefore, please make sure to fill up your brand-new car with the right fuel before taking it for a spin around the neighborhood.
The following gives a quick overview of page tagging/event tracking (coupled with handling Nosto product recommendations and banners) for headless and SPA (Single Page Application) builds. You can find more details in the , but this page will already give you a general understanding of the concept.
Search and Category Merchandising is separate from the personalization guide and covered at the end of this page.
On every page visit, you need to send a request to Nosto using our Session API about the page type the user is browsing and what exactly they're looking at (e.g. type = product, ID = 123).
You can find the different page types here, the concept is the same every time.
Nosto then returns a response with two types of content:
Product Recommendations -> JSONResult with an array of JSONProduct
Onsite Content Personalization (OCP, e.g. banners or text) -> HTML
You take the response and pass it to your rendering function, building the HTML template and injecting it into your theme.
This is done via "placements" (empty divs on every page that can be populated from the backend, e.g. pdp-top, pdp-mid, home-1, home-2, ...) and you pass all the placement-IDs that are on the current page to Nosto. Nosto then returns the data of the campaigns that are inside of those placements.
Using placements gives the eCom-team a high degree of flexibility since they can control what to show where and they can run A/B tests within Nosto.
Nosto offers you several helper functions to simplify injecting your campaigns and setting up click attribution. If you want to read more on DOM injection and click attribution read this.
The event tracking can also be done via GraphQL.
The concept is the same: specify data about the session (cart and customer) and request product recommendations for a given page type.
Please beware of the following drawbacks:
You request the campaigns for a specific product ID or category (without placements) and will receive the Recommendation campaign IDs directly and therefore can't use Nosto built-in A/B testing. You need an alternative, full page A/B testing like Omniconvert in this case.
Dynamic filtering is not possible via GraphQL. We highly recommend to go with the Session API and use viewCustomField.
Nosto OCP (like personalized banners or other HTML content) can not be retrieved via GraphQL.
The Nosto team is happy to support you finding the method that matches your tech stack, requirements and preferences. We highly recommend reading our personalization implementation guide, but if you're in a hurry, take a look at our comparison table.
Here you can find an overview of all implementation methods.
The differences between the GraphQL API and JS Library (wrapping the GraphQL API) are:
Queries done with the JS Library are automatically tracked, only clicks need to be tracked (when a user clicks on a product that was returned by a Nosto-powered search overlay, SERP or PLP)
Nosto A/B testing is automatically included with the JS Library and needs to be handled explicitly when using GraphQL
Personalized and segmented results with GraphQL need an addition of the JS Library to get the current session params from the browser and pass it to the GraphQL request
The endpoints and requests are very similar, you either pass a search query or a category and Nosto returns all products and associated facets. Here are several examples for pagination, sorting, faceting etc..
Nosto provides plugins for the most common eCommerce platforms like Shopify, Magento 2, Shopware 6, BigCommerce and Prestashop.
The plugins have implemented the Nosto backend APIs so in most cases 90% of the product catalog sync is already handled.
If your client has custom use cases, you likely will have to extend the Nosto plugin, change the data structure within your platform or make use of one of the Nosto backend APIs to ensure all the needed product data is in Nosto.
Depending on your platform, a Nosto plugin (like for Shopware or Magento 2) extends the default theme (like Dawn, Storefront, Luma or Hyvä) and implements the frontend mechanisms that are explained in the following.
Some platform plugins only include a very basic frontend component like adding the Nosto script and the page tagging.
If your client has a custom frontend (running headless or a SPA*), you will need to implement the frontend mechanisms one by one.
*This guide focuses on classic web applications that work with full page reloads. For SPAs/PWAs like React, the same principles apply but they are handled differently. We encourage you to first read through the guiding principles and in a next step make yourself familiar with the implementation within a Single Page Application.
Sending/updating the Product Catalog via GraphQL API (or REST API) to Nosto regularly.
For custom platforms (without Nosto plugin), you must use one of the APIs and build the product sync yourself (no CSV or feed option). If you’re working with PHP, you can use the Nosto PHP-SDK.
Page tagging via JavaScript or hidden HTML on all pages
Nosto provides like Shopify, Magento 2, Shopware 6, BigCommerce and Prestashop.
We recommend using our plugins as a base since they follow platform- and Nosto-specific best practices, save you lots of development time and have been tested in hundreds of eCommerce sites.
Every Nosto module falls into one of two module types which have their own set of possible implementation methods:
Campaign Widgets: Product Recommendations, Dynamic Bundles and Onsite Content Personalization (via placements, see previous section, points 3 and 4)
Listings: Search and Category Merchandising (replacing native content (Autocomplete/Search Preview, SERPs, PLPs), see previous section, point 5)
All of the following questions can be answered with our general and platform-specific documentation. For custom builds and advanced implementations you find additional playbooks below. Our onboarding team is happy to assist you with the evaluation and planning.
We have prepared dedicated playbooks for advanced setups.
In these cases you might be able to use parts of the Nosto plugins (e.g. for a Shopify headless frontend you can use our app for the data sync but need to implement the frontend components yourself).
We're happy to help you find the ideal approach for your particular tech stack. Please read the matching playbook prior to our conversation:
Headless and SPA (Single Page Application) Frontend:
Shopify Hydrogen:
Magento Hyvä:
Custom Platform/Use Case: Product Data Sync |
Depending on which Nosto modules your client has purchased, you need to determine how to implement each of those types. You can weigh the different methods and find the best approach for your tech stack, preferences and client needs with the resources below.
Campaign Widgets:
Listings:
The current cart content and logged in user information need to be available on all pages.
Placements (empty divs) where Nosto content can be injected.
These placements should be added into the HTML, most Nosto plugins offer CMS blocks for easier use.
Injecting personalized content into the placements of the current page (banners, product recommendation carousels/grids, ...)
This involves a simple request/response pattern: Tell Nosto which placements are on the current page and you’ll receive the content as JSON or HTML.
Replacing native platform features like product listings (PLPs and SERPs) with facets, pagination and sorting options.
Attribution and recording of certain events when a user interacts with a Nosto module, for example:
Impressions: Products returned from a search query
Clicks/Showing interest in a product by clicking "view more" on a PLP or SERP, from the search overlay or from a product recommendations carousel:
Can be a redirect to a PDP or
When a popup/modal (quick view) is triggered
A client that defines merchandising rules, fine-tunes the search functionality, creates recommendation campaigns, A/B tests etc. and does not need to interact with your code.
Custom Platform/Use Case: Order Data Sync GraphQL