diff --git a/getting-started/headless-spa-frontend-implementation-methods.md b/getting-started/headless-spa-frontend-implementation-methods.md new file mode 100644 index 0000000..e31c849 --- /dev/null +++ b/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). diff --git a/getting-started/what-nosto-does-and-how-it-works.md b/getting-started/what-nosto-does-and-how-it-works.md new file mode 100644 index 0000000..02e2aea --- /dev/null +++ b/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) \ No newline at end of file