@jetshop/flight-nosto

flight-nosto

This package helps you to implement Nosto in your Flight shop. It handles tracking/tagging of different page types, attribution (meaning that Nosto will know if you have clicked on their recommendations) as well as product recommendations.

Before you set it up, make sure that you have access to the Nosto dashboard.

Getting Started with Nosto

In order to integrate your flight shop with nosto you must first install it:

yarn add @jetshop/flight-nosto

Adding the Nosto Provider and cart tagging

Now that Nosto has been added into the shop, you must wrap your shop in the FlightNostoProvider. We also need the cart to be tagged here.

import { FlightNostoProvider, FlightNostoCart } from '@jetshop/flight-nosto';
import cartQuery from '../path/to/your/cartQuery.gql';
import { useCart } from '@jetshop/core/components/Query/CartProvider';

function Shop() {
  const { cart } = useCart(cartQuery);
  return (
    <FlightNostoProvider>
      <FlightNostoCart cart={cart} />
      {/* The rest of your shop components */}
    </FlightNostoProvider>
  );
}

The FlightNostoProvider component adds the Nosto script to your site, and keeps track of all the other Nosto components on the page. FlightNostoCart is used to notify Nosto about products that are put in the cart.

Now that the FlightNostoProvider has been added we can now add tagging to your different pages.

Adding Tagging

Product page

Tagging the product page is important since Nosto uses this to populate their product data, and also because the attribution is done inside this component. Currently since the variation context is being deprecated we recommend passing the selectedVariation and product to the FlightNostoProduct component as props. This will be required in the future.

To ensure proper tagging on the product page please add the FlightNostoProduct component to your ProductPage:

import { FlightNostoProduct } from '@jetshop/flight-nosto';
import { useProductVariants } from '@jetshop/core/hooks/useProductVariants';

function ProductPage({ product }) {
  const { selectedVariant } = useProductVariants(product);
  return (
    <Fragment>
      <FlightNostoProduct
        selectedVariation={selectedVariation}
        brand={'Levis'}
        product={product}
      />
      {/* Rest of the product page */}
    </Fragment>
  );
}

The attribution uses the query string prop called nosto to understand which recommendation block the user has clicked to get here.

Category page

To ensure proper tagging on the category page, add the FlightNostoCategory component to your CategoryPage;

import { FlightNostoCategory } from '@jetshop/flight-nosto';

class Category extends Component {
  render() {
    const { category, result } = this.props;
    return (
      <Fragment>
        <FlightNostoCategory
          category={category}
          route={result.data && result.data.route}
        />
        {/* Rest of the category page */}
      </Fragment>
    );
  }
}

Search page

To ensure proper tagging on the search page please add the NostoSearch component to your SearchResults:

import { NostoSearch } from '@jetshop/flight-nosto';

const SearchResults = ({ loading, ...props }) => {
  const { term } = props;
  return (
    <Fragment>
      <NostoSearch searchTerm={term} />
      {/* Rest of the search page */}
    </Fragment>
  );
};

Other pages

The other types of pages you should add tagging to is front (start page) and notfound (404 page). To do this, use the NostoPage component and pass the page type:

import { NostoPage } from '@jetshop/flight-nosto';

const StartPage = () => {
  return (
    <Fragment>
      <NostoPage pageType="front" />
      {/* Rest of the start page */}
    </Fragment>
  );
};

Product recommendations

There's a few things you have to do to set up the Nosto recommendations.

Set up template in the Nosto dashboard

First, you need to update the template in the Nosto dashboard. flight-nosto expects a specific JSON structure, so update the template to look like this:

{
    "title" : "$!title",
    "productIds":[
        #foreach($product in $products)
            #if($foreach.count>1),#end
            "$!product.productId.escapeJsonString()"
        #end
    ]
}

Fetch the product data

The template above will only provide the title and productIds for the recommendation, so we need to fetch the full product data ourselves.

First, we create a query that takes ids and fetches the data we want:

#import "@jetshop/core/data/fragments/RouteCrumbFragment.gql"
#import "@jetshop/core/data/fragments/ProductPriceFragment.gql"
#import "@jetshop/core/data/fragments/BadgeFragment.gql"

query NostoProductRecosQuery(
  $ids: [Int] = null
  $articleNumbers: [String] = null
) {
  products(articleNumbers: $articleNumbers, ids: $ids) {
    id
    articleNumber
    name
    subName
    shortDescription
    description
    mainHeader
    primaryRoute {
      ...RouteCrumb
    }
    ...ProductPrice
    images {
      alt
      title
      url
    }
    badges {
      ...Badge
    }
  }
}

Then we pass this query into the FlightNostoRecos component. If you would like to use articleNumbers instead of ids for your products please set the boolean prop articleNumbers to true:

import React from 'react';
import { FlightNostoRecos } from '@jetshop/flight-nosto';
import GridProduct from '@jetshop/ui/ProductList/GridProduct';
import nostoRecosProductQuery from './NostoRecosProductQuery.gql';

const Product = ({ result: { data, loading }, product }) => {
  const nostoId = 'my-nosto-recommendation-id';
  return (
    <div>
      {/* ... Your Product page */}
      <FlightNostoRecos
        query={nostoRecosProductQuery}
        id={nostoId}
        articleNumbers={false}
      >
        {({ products }) => {
          return products.map(product => (
            <GridProduct
              key={product.id}
              product={product}
              search={`?nosto=${nostoId}`}
            />
          ));
        }}
      </FlightNostoRecos>
    </div>
  );
};

export default Product;

Also note that we pass a query string to the GridProduct component. This is used in the FlightNostoProduct component to do the correct attribution of the Nosto recommendation element - meaning that Nosto will know what product recommendation the user clicked to get to the product page.

That's it!