Add "Getting started guide" and Headless Overview

SUMMARY.md

@@ -1,9 +1,18 @@
 # Table of contents
 
-* [Introduction](README.md)
+## Getting started
+
+* [Welcome and support](getting-started/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
 
+* [Introduction](README.md)
 * [Implement on your website](implementing-nosto/implement-on-your-website/README.md)
   * [Manual Implementation - Essentials](implementing-nosto/implement-on-your-website/manual-implementation/README.md)
     * [Setting up your account](implementing-nosto/implement-on-your-website/manual-implementation/setting-up-your-account.md)
@@ -27,6 +36,7 @@
   * [FAQ](implementing-nosto/implement-on-your-website/faq.md)
 * [Implement on native mobile](implementing-nosto/implement-on-native-mobile.md)
 * [Implement on a physical store](implementing-nosto/implement-on-physical-store.md)
+* [Implement Personalized Campaign Widgets](implementing-nosto/implement-psn/README.md)
 * [Implement Search & Categories](implementing-nosto/implement-search/README.md)
   * [Using Search Templates Starter](implementing-nosto/implement-search/using-search-templates-starter/README.md)
     * [Getting started](implementing-nosto/implement-search/using-search-templates-starter/getting-started.md)

apis/frontend/implementation-guide-session-api/spa-basics-leveraging-features.md

@@ -68,6 +68,7 @@ When a recommended product is viewed, the `result_id` from the recommendation re
             "result_type": "REAL",
             "title": "Most Popular Right Now",
             "div_id": "nosto-frontpage-1" // requested placement id
+        }
     }
 }
 ```

apis/frontend/implementation-guide-session-api/spa-basics-tracking-events.md

@@ -1,5 +1,9 @@
 # Tracking Events
 
+Instead of using [HTML tagging or tagging providers](../../../implementing-nosto/implement-on-your-website/manual-implementation/README.md), you will implement the same pattern for event tracking on all page types. Nosto needs to know what is happening during a user's session, mainly page views (like PDPs or PLPs), "add to cart" events and conversions.
+
+Regardless if an event was influenced by a Nosto personalization module (product recommendation/bundle or on-site content like a personalized banner) or not, **the fundamental call you make is always the same and varies on the page type**. When a shopper visits the homepage, you will call `viewFrontPage()`, when a search was made for "black shoes" you will call `.viewSearch("black shoes")` and so on. **All page types are listed with examples below**.
+
 ## Upon viewing the homepage
 
 When viewing a homepage, there's no context to be provided, so invoking the `viewFrontPage` will suffice.

getting-started/README.md

@@ -0,0 +1,9 @@
+# Welcome and support
+
+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](mailto:onboarding@nosto.com) so we can a) support you and b) update our information.

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

@@ -0,0 +1,99 @@
+# 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.
+
+
+## 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 navtive 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)
+- 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,48 @@
+# 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. You will
+
+Search and Category Merchandising is separate from that and covered afterwards.
+
+
+## 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), 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)s
+- 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) 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).