@nosto/nosto-react 0.2.1 → 0.4.0

package/src/components/Placement/index.client.tsx

@@ -1,11 +1,22 @@
 import React from "react";
 
-export interface PlacementProps {
+/**
+ * Nosto React has a special component called NostoPlacement.
+ * The component is a simply a hidden `<div>` placeholder into which Nosto injects recommendations or personalises the content between the tags.
+ *
+ * We recommend adding as many placements across your views as needed as these are hidden and only populated when a corresponding campaign (targeting that placement) is configured.
+ *
+ * @example
+ * ```
+ * <NostoPlacement id="frontpage-nosto-1" />
+ * ```
+ *
+ * @group Personalisation Components
+ */
+export default function NostoPlacement(props: {
   id: string;
+  pageType?: string;
+}): JSX.Element {
+  const { id, pageType } = props;
+  return <div className="nosto_element" id={id} key={id + (pageType || "")} />;
 }
-
-const NostoPlacement: React.FC<PlacementProps> = ({ id }) => {
-  return <div className="nosto_element" id={id} />;
-};
-
-export default NostoPlacement;

package/src/components/Product/index.client.tsx

@@ -1,39 +1,67 @@
 import { Product } from "../../types";
-import React, { useEffect } from "react";
 import { useNostoContext } from "../Provider/context.client";
+import { useDeepCompareEffect } from "../../utils/hooks";
 
-const NostoProduct: React.FC<{ product: string; tagging: Product }> = ({
-  product,
-  tagging,
-}) => {
-  const { clientScriptLoaded, currentVariation, renderFunction, responseMode } =
-    useNostoContext();
+/**
+ * The NostoProduct component must be used to personalise the product page.
+ * The component requires that you provide it the identifier of the current product being viewed.
+ *
+ * By default, your account, when created, has three product-page placements named `productpage-nosto-1`, `productpage-nosto-2` and `productpage-nosto-3`.
+ * You may omit these and use any identifier you need.
+ * The identifiers used here are simply provided to illustrate the example.
+ *
+ * The `<NostoProduct \>` component needs to be added after the placements.
+ * Content and recommendations will be rendered through this component.
+ * Pass in the product ID via the product prop to pass this information back to Nosto.
+ *
+ * @example
+ * ```
+ * <div className="product-page">
+ *   <NostoPlacement id="productpage-nosto-1" />
+ *   <NostoPlacement id="productpage-nosto-2" />
+ *   <NostoPlacement id="productpage-nosto-3" />
+ *   <NostoProduct product={product.id} />
+ * </div>
+ * ```
+ *
+ * @group Personalisation Components
+ */
+export default function NostoProduct(props: {
+  product: string;
+  tagging?: Product;
+}): JSX.Element {
+  const { product, tagging } = props;
+  const {
+    clientScriptLoaded,
+    currentVariation,
+    responseMode,
+    recommendationComponent,
+    useRenderCampaigns,
+  } = useNostoContext();
 
-  useEffect(() => {
-    // @ts-ignore
-    if (clientScriptLoaded) {
-      window.nostojs(
-        (api: any) => {
-          api
-            .defaultSession()
-            .setResponseMode(responseMode)
-            .viewProduct(product)
-            .setPlacements(api.placements.getPlacements())
-            .load()
-            .then((data: object) => {
-              if (responseMode == "HTML") {
-                // @ts-ignore
-                api.placements.injectCampaigns(data.recommendations);
-              } else {
-                // @ts-ignore
-                renderFunction(data.campaigns);
-              }
-            });
-        },
-        [clientScriptLoaded, currentVariation, product, renderFunction]
-      );
+  const { renderCampaigns, pageTypeUpdated } = useRenderCampaigns("product");
+
+  useDeepCompareEffect(() => {
+    if (clientScriptLoaded && pageTypeUpdated) {
+      window.nostojs((api) => {
+        api
+          .defaultSession()
+          .setResponseMode(responseMode)
+          .viewProduct(product)
+          .setPlacements(api.placements.getPlacements())
+          .load()
+          .then((data) => {
+            renderCampaigns(data, api);
+          });
+      });
     }
-  });
+  }, [
+    clientScriptLoaded,
+    currentVariation,
+    product,
+    recommendationComponent,
+    pageTypeUpdated,
+  ]);
 
   return (
     <>
@@ -155,6 +183,4 @@ const NostoProduct: React.FC<{ product: string; tagging: Product }> = ({
       </div>
     </>
   );
-};
-
-export default NostoProduct;
+}

package/src/components/Provider/context.client.ts

@@ -1,23 +1,40 @@
 import { createContext, useContext } from "react";
+import { Recommendation } from "../../types";
 
-export interface NostoInterface {
+/**
+ * @group Types
+ */
+export interface NostoContextType {
   account: string;
   clientScriptLoaded: boolean;
   currentVariation: string;
   renderFunction?: Function;
   responseMode: string;
+  recommendationComponent?: React.ReactElement<{
+    nostoRecommendation: Recommendation;
+  }>;
+  useRenderCampaigns: Function;
+  pageType: string;
 }
 
-/* tslint:disable:no-empty */
-export const NostoContext = createContext<NostoInterface>({
-  // @ts-ignore
-  account: undefined,
+/**
+ * @group Essential Functions
+ */
+export const NostoContext = createContext<NostoContextType>({
+  account: "",
   currentVariation: "",
-  renderFunction: undefined,
+  pageType: "",
+  responseMode: "HTML",
+  clientScriptLoaded: false,
+  useRenderCampaigns: () => undefined,
 });
 
-/* tslint:enable:no-empty */
-export function useNostoContext() {
+/**
+ * A hook that allows you to access the NostoContext and retrieve Nosto-related data from it in React components.
+ *
+ * @group Essential Functions
+ */
+export function useNostoContext(): NostoContextType {
   const context = useContext(NostoContext);
 
   if (!context) {

package/src/components/Provider/index.client.tsx

@@ -1,23 +1,68 @@
-import React, { useEffect } from "react";
+import React, { useEffect, isValidElement, useState, useRef } from "react";
 import { NostoContext } from "./context.client";
+import { createRoot } from "react-dom/client";
+import { Recommendation } from "../../types";
 
-interface NostoProviderProps {
+/**
+ * This widget is what we call the Nosto root widget, which is responsible for adding the actual Nosto script and the JS API stub.
+ * This widget wraps all other React Nosto widgets.
+ *
+ * ```
+ * <NostoProvider account="your-nosto-account-id" recommendationComponent={<NostoSlot />}>
+ *   <App />
+ * </NostoProvider>
+ * ```
+ *
+ * **Note:** the component also accepts a prop to configure the host `host="connect.nosto.com"`.
+ * In advanced use-cases, the need to configure the host may surface.
+ *
+ * In order to implement client-side rendering, the requires a designated component to render the recommendations provided by Nosto.
+ * This component should be capable of processing the JSON response received from our backend.
+ * Notice the `recommendationComponent` prop passed to `<NostoProvider>` above.
+ *
+ * Learn more [here](https://github.com/Nosto/shopify-hydrogen/blob/main/README.md#client-side-rendering-for-recommendations) and see a [live example](https://github.com/Nosto/shopify-hydrogen-demo) on our demo store.
+ *
+ * @group Essential Functions
+ */
+export default function NostoProvider(props: {
+  /**
+   * Indicates merchant id
+   */
   account: string;
-  currentVariation: string;
-  host: string;
+  /**
+   * Indicates currency
+   */
+  currentVariation?: string;
+  /**
+   * Indicates an url of a server
+   */
+  host?: string;
   children: React.ReactElement;
-  multiCurrency: boolean;
-  renderFunction?: Function;
-}
-
-const NostoProvider: React.FC<NostoProviderProps> = ({
-  account,
-  currentVariation = "",
-  multiCurrency = false,
-  host,
-  children,
-  renderFunction,
-}) => {
+  /**
+   * Indicates if merchant uses multiple currencies
+   */
+  multiCurrency?: boolean;
+  /**
+   * Recommendation component which holds nostoRecommendation object
+   */
+  recommendationComponent?: any;
+  /**
+  * Enables Shopify markets with language and market id
+  */
+  shopifyMarkets?: {
+    language?: string;
+    marketId?: string | number;
+  }
+}): JSX.Element {
+  let {
+    account,
+    currentVariation = "",
+    multiCurrency = false,
+    host,
+    children,
+    recommendationComponent,
+    shopifyMarkets
+  } = props;
   const [clientScriptLoadedState, setClientScriptLoadedState] =
     React.useState(false);
   const clientScriptLoaded = React.useMemo(
@@ -25,32 +70,139 @@ const NostoProvider: React.FC<NostoProviderProps> = ({
     [clientScriptLoadedState]
   );
 
-  //Set responseMode for loading campaigns:
-  const responseMode =
-    typeof renderFunction == "function" ? "JSON_ORIGINAL" : "HTML";
-
   //Pass currentVariation as empty string if multiCurrency is disabled
   currentVariation = multiCurrency ? currentVariation : "";
 
+  // Set responseMode for loading campaigns:
+  const responseMode = isValidElement(recommendationComponent)
+    ? "JSON_ORIGINAL"
+    : "HTML";
+
+  // RecommendationComponent for client-side rendering:
+  function RecommendationComponentWrapper(props: {
+    nostoRecommendation: Recommendation;
+  }) {
+    return React.cloneElement(recommendationComponent!, {
+      nostoRecommendation: props.nostoRecommendation,
+    });
+  }
+
+  // custom hook for rendering campaigns (CSR/SSR):
+  const [pageType, setPageType] = useState("");
+  const useRenderCampaigns: any = function (type: string = "") {
+    const placementRefs: any = useRef({});
+    useEffect(() => {
+      if (pageType != type) {
+        setPageType(type);
+      }
+    }, []);
+
+    const pageTypeUpdated = type == pageType;
+
+    function renderCampaigns(
+      data: {
+        recommendations: any;
+        campaigns: {
+          recommendations: {
+            [key: string]: any;
+          };
+        };
+      },
+      api: {
+        placements: {
+          injectCampaigns: (recommendations: any) => void;
+        };
+      }
+    ) {
+      if (responseMode == "HTML") {
+        // inject content campaigns as usual:
+        api.placements.injectCampaigns(data.recommendations);
+      } else {
+        // render recommendation component into placements:
+        const recommendations = data.campaigns.recommendations;
+        for (const key in recommendations) {
+          let recommendation = recommendations[key];
+          let placementSelector = "#" + key;
+          let placement: Function = () =>
+            document.querySelector(placementSelector);
+
+          if (!!placement()) {
+            if (!placementRefs.current[key])
+              placementRefs.current[key] = createRoot(placement());
+            const root = placementRefs.current[key];
+            root.render(
+              <RecommendationComponentWrapper
+                nostoRecommendation={recommendation}
+              ></RecommendationComponentWrapper>
+            );
+          }
+        }
+      }
+    }
+    return { renderCampaigns, pageTypeUpdated };
+  };
+
+
   useEffect(() => {
-    if (!document.querySelectorAll("[nosto-client-script]").length) {
+    if (!window.nostojs) {
+      window.nostojs = (cb: Function) => {
+        (window.nostojs.q = window.nostojs.q || []).push(cb);
+      };
+      window.nostojs((api) => api.setAutoLoad(false));
+    }
+
+    if (!document.querySelectorAll("[nosto-client-script]").length && !shopifyMarkets) {
       const script = document.createElement("script");
       script.type = "text/javascript";
       script.src = "//" + (host || "connect.nosto.com") + "/include/" + account;
       script.async = true;
       script.setAttribute("nosto-client-script", "");
+
       script.onload = () => {
-        console.log("Nosto client script loaded");
+        if (typeof jest !== "undefined") {
+          window.nosto?.reload({
+            site: "localhost",
+          });
+        }
         setClientScriptLoadedState(true);
       };
-      document.head.appendChild(script);
+      document.body.appendChild(script);
+    }
+
+    //Enable Shopify markets functionality:
+    if (!!shopifyMarkets) {
+
+      const existingScript = document.querySelector("[nosto-client-script]");
+      const nostoSandbox = document.querySelector('#nosto-sandbox');
+
+      if (!existingScript || existingScript?.getAttribute('nosto-language') != shopifyMarkets?.language || existingScript?.getAttribute('nosto-market-id') != shopifyMarkets?.marketId) {
+        if (clientScriptLoadedState) { setClientScriptLoadedState(false) };
+
+        existingScript?.parentNode?.removeChild(existingScript)
+        nostoSandbox?.parentNode?.removeChild(nostoSandbox)
+
+        const script = document.createElement("script");
+        script.type = "text/javascript";
+        script.src = "//" + (host || "connect.nosto.com") + `/script/shopify/market/nosto.js?merchant=${account}&market=${shopifyMarkets.marketId || ''}&locale=${shopifyMarkets?.language?.toLowerCase() || ''}`
+        script.async = true;
+        script.setAttribute("nosto-client-script", "");
+        script.setAttribute("nosto-language", shopifyMarkets?.language || '');
+        script.setAttribute("nosto-market-id", String(shopifyMarkets?.marketId));
+
+        script.onload = () => {
+          if (typeof jest !== "undefined") {
+            window.nosto?.reload({
+              site: "localhost",
+            });
+          }
+          setClientScriptLoadedState(true);
+        };
+        document.body.appendChild(script);
+      }
+
     }
 
-    window.nostojs = (cb: Function) =>
-      (window.nostojs.q = window.nostojs.q || []).push(cb);
-    // @ts-ignore
-    window.nostojs((api) => api.setAutoLoad(false));
-  }, []);
+  }, [clientScriptLoadedState, shopifyMarkets]);
 
   return (
     <NostoContext.Provider
@@ -58,13 +210,13 @@ const NostoProvider: React.FC<NostoProviderProps> = ({
         account,
         clientScriptLoaded,
         currentVariation,
-        renderFunction,
         responseMode,
+        recommendationComponent,
+        useRenderCampaigns,
+        pageType,
       }}
     >
       {children}
     </NostoContext.Provider>
   );
-};
-
-export default NostoProvider;
+}

package/src/components/Search/index.client.tsx

@@ -1,14 +1,44 @@
-import React, { useEffect } from "react";
+import { useEffect } from "react";
 import { useNostoContext } from "../Provider/context.client";
 
-const NostoSearch: React.FC<{ query: string }> = ({ query }) => {
-  const { clientScriptLoaded, currentVariation, renderFunction, responseMode } =
-    useNostoContext();
+/**
+ * You can personalise your search pages by using the NostoSearch component.
+ * The component requires that you provide it the current search term.
+ *
+ * By default, your account, when created, has two search-page placements named `searchpage-nosto-1` and `searchpage-nosto-2`.
+ * You may omit these and use any identifier you need. The identifiers used here are simply provided to illustrate the example.
+ *
+ * @example
+ * ```
+ * <div className="search-page">
+ *   <NostoPlacement id="searchpage-nosto-1" />
+ *   <NostoPlacement id="searchpage-nosto-2" />
+ *   <NostoSearch query={"black shoes"} />
+ * </div>
+ * ```
+ *
+ * **Note:** Do not encode the search term in any way.
+ * It should be provided an unencoded string.
+ * A query for `black shoes` must be provided as-is and not as `black+shoes`.
+ * Doing so will lead to invalid results.
+ *
+ * @group Personalisation Components
+ */
+export default function NostoSearch(props: { query: string }): JSX.Element {
+  const { query } = props;
+  const {
+    clientScriptLoaded,
+    currentVariation,
+    responseMode,
+    recommendationComponent,
+    useRenderCampaigns,
+  } = useNostoContext();
+
+  const { renderCampaigns, pageTypeUpdated } = useRenderCampaigns("search");
 
   useEffect(() => {
-    // @ts-ignore
-    if (clientScriptLoaded) {
-      window.nostojs((api: any) => {
+    if (clientScriptLoaded && pageTypeUpdated) {
+      window.nostojs((api) => {
         api
           .defaultSession()
           .setVariation(currentVariation)
@@ -16,18 +46,18 @@ const NostoSearch: React.FC<{ query: string }> = ({ query }) => {
           .viewSearch(query)
           .setPlacements(api.placements.getPlacements())
           .load()
-          .then((data: object) => {
-            if (responseMode == "HTML") {
-              // @ts-ignore
-              api.placements.injectCampaigns(data.recommendations);
-            } else {
-              // @ts-ignore
-              renderFunction(data.campaigns);
-            }
+          .then((data) => {
+            renderCampaigns(data, api);
           });
       });
     }
-  }, [clientScriptLoaded, currentVariation, query, renderFunction]);
+  }, [
+    clientScriptLoaded,
+    currentVariation,
+    query,
+    recommendationComponent,
+    pageTypeUpdated,
+  ]);
 
   return (
     <>
@@ -39,6 +69,4 @@ const NostoSearch: React.FC<{ query: string }> = ({ query }) => {
       </div>
     </>
   );
-};
-
-export default NostoSearch;
+}

package/src/components/Session/index.client.tsx

@@ -1,24 +1,31 @@
-import React from "react";
-import snakeize from "snakeize";
 import { useNostoContext } from "../Provider/context.client";
-
-import useDeepCompareEffect from "use-deep-compare-effect";
 import { Cart, Customer } from "../../types";
+import { snakeize } from "../../utils/snakeize";
+import { useDeepCompareEffect } from "../../utils/hooks";
 
-interface NostoSessionProps {
+/**
+ * Nosto React requires that you pass it the details of current cart contents and the details of the currently logged-in customer, if any, on every route change.
+ * This makes it easier to add attribution.
+ *
+ * The `NostoSession` component makes it very easy to keep the session up to date so long as the cart and the customer are provided.
+ *
+ * The cart prop requires a value that adheres to the type `Cart`, while the customer prop requires a value that adheres to the type `Customer`.
+ *
+ * @group Essential Functions
+ */
+export default function NostoSession(props: {
   cart: Cart;
   customer: Customer;
-}
-
-const NostoSession: React.FC<NostoSessionProps> = ({ cart, customer }) => {
+}): JSX.Element {
+  const { cart, customer } = props;
   const { clientScriptLoaded } = useNostoContext();
+
   useDeepCompareEffect(() => {
-    const currentCart = cart ? snakeize(cart) : undefined;    
+    const currentCart = cart ? snakeize(cart) : undefined;
     const currentCustomer = customer ? snakeize(customer) : undefined;
 
-    // @ts-ignore
     if (clientScriptLoaded) {
-      window.nostojs((api: any) => {
+      window.nostojs((api) => {
         api
           .defaultSession()
           .setResponseMode("HTML")
@@ -28,9 +35,7 @@ const NostoSession: React.FC<NostoSessionProps> = ({ cart, customer }) => {
           .load();
       });
     }
-  }, [clientScriptLoaded, cart || [], customer || {}]);
+  }, [clientScriptLoaded, cart, customer]);
 
   return <></>;
-};
-
-export default NostoSession;
+}

package/src/index.client.ts

@@ -1,12 +1,6 @@
-declare global {
-  // noinspection JSUnusedGlobalSymbols
-  interface Window {
-    nostojs: any;
-    nosto: any;
-  }
-}
-
-export * from "./types";
+export type {
+  Buyer, Cart, Customer, Item, Product, Purchase, Recommendation, SKU
+} from "./types";
 // noinspection JSUnusedGlobalSymbols
 export { default as Nosto404 } from "./components/Fohofo/index.client";
 // noinspection JSUnusedGlobalSymbols
@@ -32,6 +26,8 @@ export {
   NostoContext,
   useNostoContext,
 } from "./components/Provider/context.client";
+export type {
+  NostoContextType,
+} from "./components/Provider/context.client";
 // noinspection JSUnusedGlobalSymbols
-export { default as NostoSession } from "./components/Session/index.client";
-//
+export { default as NostoSession } from "./components/Session/index.client";