Add "Getting started guide" and Headless Overview

README.md

@@ -1,23 +1,9 @@
-# Introduction
+# Welcome and support
 
-This guide introduces you how to implement Nosto on a e-commerce store that does not yet have a dedicated plugin solution. The articles are designed as digestable step-by-step guides that walk you through how to establish the data exchange between the site and Nosto.
+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.
 
-First its important to understand a few of the concepts before delving in to the documentation, to make sure that you as a integrator understand the different steps and tools required.
+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.
 
-* Nosto initializes by using a [snippet of Javascript](implementing-nosto/implement-on-your-website/manual-implementation/add-nosto-script.md) that starts the dialogue to your dedicated account. 
-* Nosto depends on structured data that we extract from your site. At the bare minimum you need to go through all the steps listed under [Manual Implementation - Essentials](implementing-nosto/implement-on-your-website/manual-implementation/).
-* You can augment and extend the product tagging and the data collection process with the help of other articles found under this guide. 
-* You can access your own account in the Nosto admin UI [my.nosto.com/admin](https://my.nosto.com/admin) where you can enable/configure/modify features. All templating and layouts are handled within your account.
-
-In case you have already implemented Nosto and established continuous data exchange you can find more information related to troubleshooting or setting up features at [help.nosto.com](https://help.nosto.com/).
-
-**Implementation Checklist**
-
-As a first step, please check if your e-commerce platform or software is already supported by a Nosto extension or integration. In case the platform is supported we warmly recommend to use an extension and reading the platform specific guide as this saves you some manual effort and time, since the implementation process differs a bit from the one described in this article series and practically automates all the steps.
-
-Second, make sure that you have a Nosto account and if not, sign up on Nosto home page or contact Nosto sales.
-
-Every Nosto account has a unique identifier known as `accountID`, which is required in the implementation. If you know that you have an account, but don’t know your `accountID`, log-in to your Nosto admin panel and learn where you can find it!
-
-Third, if you first implement Nosto on a local device or on a development environment, bookmark this article about implementing Nosto on a test environment for later reading. No need to jump there yet, as it is also featured as the last article in this series.
+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](https://www.nosto.com/contact/) so we can a) support you and b) update our information.

SUMMARY.md

@@ -1,6 +1,14 @@
 # Table of contents
 
-* [Introduction](README.md)
+## Quick Start Guide
+
+* [Welcome and support](README.md)
+* [How to get the most out of our guides and Nosto](getting-started/how-to-get-the-most-out-of-our-guides-and-nosto.md)
+* [What Nosto does and how it works](getting-started/what-nosto-does-and-how-it-works.md)
+* [What Nosto needs](getting-started/what-nosto-needs.md)
+* [How you ensure a clean and quick implementation](getting-started/how-you-ensure-a-clean-and-quick-implementation.md)
+* [Building your implementation plan](getting-started/building-your-implementation-plan.md)
+* [Headless and SPA (Single Page Application) implementation methods](getting-started/headless-spa-frontend-implementation-methods.md)
 
 ## Implementing Nosto
 

getting-started/building-your-implementation-plan.md

@@ -0,0 +1,103 @@
+# Building your Implementation Plan
+
+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.
+
+![Big Picture of a Nosto implementation, details in the next section](../.gitbook/assets/Nosto-Big-Picture.png)
+
+
+## Components of a stable Nosto Implementation
+
+1. 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.
+2. Page tagging via JavaScript or hidden HTML on all pages
+   - There are several page types, so please make sure they are covered in your QA checklist. (You can use ours as a blueprint.)
+   - The current cart content and logged in user information **need to be available on all pages**.
+3. 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.
+4. 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.
+5. Replacing native platform features like product listings (PLPs and SERPs) with facets, pagination and sorting options.
+6. 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
+7. 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.
+
+
+## Resources to evaluate and choose the Implementation Methods
+
+Nosto provides [plugins for the most common eCommerce platforms](https://docs.nosto.com/techdocs/implementing-nosto/implement-on-your-website#choosing-the-implementation-method) 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.
+
+### Nosto Module Types and Frontend Implementation Methods
+
+Every Nosto module falls into one of two module types which have their own set of possible implementation methods:
+
+1. **Campaign Widgets:** Product Recommendations, Dynamic Bundles and Onsite Content Personalization (via placements, see previous section, points 3 and 4)
+2. **Listings:** Search and Category Merchandising (replacing native content (Autocomplete/Search Preview, SERPs, PLPs), see previous section, point 5)
+
+### Project Plan Checklist
+
+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.
+
+- [ ] **Product Data Sync:** How do you send Nosto the product catalog?
+- [ ] **Multi-Currency and Localization:** How do you send Nosto the localized data? How do you make sure the correct language and currency shows in the frontend?
+- [ ] **Customer Group Visibility/Pricing:** How do you handle different product availability or prices depending on customer groups? If you are using SKUs/variants/child products or also have multiple currencies, you can't use Nosto's built-in functionality. We then recommend either an API implementation or fetching the prices via an frontend API.
+- [ ] **Order Data Sync:** How do you send Nosto the placed orders?
+- [ ] **Frontend Script:** How do you inject the Nosto script?
+- [ ] **Session Tagging:** How do you tag the currently logged in user and shopping cart content on all pages?
+- [ ] **Frontend Page Tagging:** How do you tag the different page types?
+- [ ] **Frontend Module Injection:** Which implementation method fits your tech stack and client needs best? (Comparison table below)
+  - [ ] Campaign Widgets: `Nosto-hosted` | `Client API` | `Server API`
+  - [ ] Listings: `Nosto-hosted` | `Client API` | `Server API`
+- [ ] **Custom Event Tracking:** How do you signal Nosto non-standard user interactions like "viewed product" or "added product to cart" events? You need this if you have features like:
+  - [ ] "Add to cart" button on product cards, 
+  - [ ] "Quick View"/"Quick Buy" modals in campaign widgets or listings,
+  - [ ] "Mini-Cart" campaign widgets, 
+  - [ ] ...
+- [ ] **Fallback Plan:** How does your frontend behave in case the Nosto service is temporarily unavailable? (The insurance we want you to never need.)
+  - [ ] Campaign Widgets: Do you fallback to native recommendations or generic banners? Do you show an empty section? Is it worth implementing a fallback?
+  - [ ] Listings: Do you fallback to your platform's native functionality? We recommend to fallback to your native PLPs and SERPs, [Nosto search templates have a "ready to use" fallback mechanism](../implementing-nosto/implement-search/implement-search-using-code-editor/implementing-search-page.md#fallback-functionality).
+- [ ] **Testing and QA**: How do you verify:
+  - [ ] Nosto receives the correct product and order data from your platform,
+  - [ ] Nosto data (product cards in product recommendations and/or product listings) is personalized, segmented and rendered in the frontend,
+  - [ ] Nosto data (product cards in product recommendations and/or product listings) match your customer grouping and localization strategy,
+  - [ ] Nosto-relevant user interactions are tracked by Nosto,
+  - [ ] Nosto-influenced user interactions are correctly attributed to orders,
+  - [ ] Nosto A/B testing functionality can be utilized for each Nosto module.
+  - [ ] Nosto modules don't interfere with your architecture (e.g. on a SPA, Nosto doesn't cause page reloads)
+  - [ ] Nosto Category Merchandising only: PLPs show the expected products, either:
+    - [ ] Only directly assigned products to a category or 
+    - [ ] Including the products of subcategories (Magento e.g. calls this an "anchored category")
+
+### Headless Builds, SPAs (Single Page Applications) and Custom Platforms
+
+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: [Implementation Methods](headless-spa-frontend-implementation-methods.md)
+- Shopify Hydrogen: [React Component Library](https://docs.nosto.com/shopify/features/shopify-hydrogen)
+- Magento Hyvä: [Built-in support in the Nosto Magento plugin](https://docs.nosto.com/magento-2/hyva-theme)
+- Custom Platform/Use Case: Product Data Sync [GraphQL](../apis/graphql-an-introduction/graphql-using-mutations/graphql-updating-products.md) | [REST](../apis/rest/products/updating-products-using-the-products-api.md)
+- Custom Platform/Use Case: Order Data Sync [GraphQL](../apis/graphql-an-introduction/graphql-using-mutations/working-with-orders/graphql-placing-orders.md)
+
+### Comparison Tables for Nosto Modules and Implementation Methods
+
+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.
+
+1. **Campaign Widgets:** [Product Recommendations, Dynamic Bundles and Onsite Content Personalization](../implementing-nosto/implement-psn/README.md#comparison-table)
+2. **Listings:** [Search and Category Merchandising](../implementing-nosto/implement-search/README.md#compare-implementations)

getting-started/headless-spa-frontend-implementation-methods.md

@@ -0,0 +1,52 @@
+# Headless and SPA Frontend: Implementation Methods
+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 [personalization implementation guide](../implementing-nosto/implement-psn/README.md), 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.
+
+{% hint style="info" %}
+If you are using Shopify Hydrogen or Magento Hyvä, you can use Nosto's dedicated [React Component Library for Shopify Hydrogen](https://docs.nosto.com/shopify/features/shopify-hydrogen) and the [built-in support for Hyvä in the Nosto Magento plugin](https://docs.nosto.com/magento-2/hyva-theme).
+{% endhint %}
+
+
+## Page Tagging and Event Tracking + Requesting Nosto Content for rendering with your Templates
+On every page visit, you need to send a request to Nosto using our [Session API](https://nosto.github.io/nosto-js/interfaces/client.Session.html) 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](../apis/frontend/implementation-guide-session-api/spa-basics-tracking-events.md), the concept is the same every time.
+
+Nosto then returns a response with two types of content:
+- Product Recommendations (RECs) -> [JSONResult](https://nosto.github.io/nosto-js/interfaces/client.JSONResult.html) with an array of [JSONProduct](https://nosto.github.io/nosto-js/interfaces/client.JSONProduct.html)
+- Onsite Content Personalization (OCP, e.g. banners or text) -> [HTML](https://nosto.github.io/nosto-js/interfaces/client.AttributedCampaignResult.html)
+
+### Nosto Content via Session API
+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"](https://help.nosto.com/en/articles/1883767-placements-general-article) (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](../implementing-nosto/implement-psn/README.md#dom-injection-and-click-attribution).
+
+### Nosto Content via GraphQL
+The event tracking can also be done via GraphQL.
+
+The concept is the same: [specify data about the session (cart and customer)](../apis/graphql-an-introduction/graphql-using-mutations/README.md) and [request product recommendations for a given page type](../apis/graphql-an-introduction/graphql-using-mutations/graphql-onsite-sessions/README.md).
+
+**Please beware of the following drawbacks:**
+1. You request the campaigns for a specific product ID or category (without placements) and will receive the RECs 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.
+2. [Dynamic filtering](../apis/frontend/js-apis/recommendations/setting-up-dynamic-filtering.md) is not possible via GraphQL. We highly recommend to go with the Session API and use [`viewCustomField`](https://nosto.github.io/nosto-js/interfaces/client.Session.html#viewcustomfield).
+3. Nosto OCP (like personalized banners or other HTML content) can not be retrieved via GraphQL.
+
+### Choosing the right Implementation Method
+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](../implementing-nosto/implement-psn/README.md), but if you're in a hurry, take a look at our [comparison table](../implementing-nosto/implement-psn/README.md#comparison-table).
+
+
+## Implementation Methods for Nosto Search/Category Merchandising (CM)
+Here you can find an [overview of all implementation methods](../implementing-nosto/implement-search/README.md#compare-implementations).
+
+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](../implementing-nosto/implement-search/search/README.md#search-product-click) (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](../implementing-nosto/implement-search/implement-search-using-api/analytics-ab-testing.md) 
+- [Personalized and segmented results with GraphQL need an addition of the JS Library](../implementing-nosto/implement-search/implement-search-using-api/using-the-search-api.md#session-params) 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.](../implementing-nosto/implement-search/implement-search-using-api/implementing-search-page.md).