Create single commit PR for getting-started files from PR #330

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).

getting-started/what-nosto-does-and-how-it-works.md

@@ -0,0 +1,16 @@
+# What Nosto does and how it works
+
+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:
+
+1. **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.
+2. **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
+        - over 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.
+
+* [Watch video: Overview of Nosto by example of a custom implementation](/.gitbook/assets/01-overview-custom-implementation.mp4)
+* [Watch video: How Nosto injects personalized content](/.gitbook/assets/02-RECs-implementation-nosto-hosted-vs-api.mp4)