JavaScript SDK
Headless

﻿
This document provides a comprehensive guide on leveraging SparkLayer in conjunction with a Shopify-powered headless storefront. At the present moment, SparkLayer's exclusive support for Shopify is due to the need for a synchronisation mechanism However, in the near future, we plan expand its capabilities, enabling the development of custom integrations that can be compatible with many other platforms.
Requirements
A Shopify store
﻿The SparkLayer App installed on the store
A metafield definition set up for the SparkLayer Authentication metafield
Enable storefronts access for this metafield definition
SparkLayer uses a customer metafield to store authentication data, which allows the SparkLayer front-end to authenticate the user with the SparkLayer API.
Overview
This is a high level overview of how SparkLayer runs on a headless site.
Get the customer data for the logged in user
Check if the customer is a b2b customer (has the tag "b2b") and has the sparklayer.authentication metafield set. If they do, continue.
Load the SparkLayer javascript by injecting a script tag such as: <script src="https://cdn.sparklayer.io/spark.1.0.26.js"></script>
When the script has loaded call window.sparkInit({ ...options }}), passing in options like siteId. More details on configuration can be found here.
Inject a style element into the  document which sets CSS variables to customise the look and behaviour of the SparkLayer components. More details here.
Additional code changes are required to: show SparkLayer components, hide elements that should not be seen by b2b customers and integrate SparkLayer with controls on your site.
Elements to hide
The following elements should be hidden for b2c customers on all pages:
Prices
Add to cart button
Quantity selector
By adding the following data attribute to the element data-spark="b2c-only", the element will be hidden when SparkLayer loads. You can learn more here.
Include SparkLayer components
You'll want to include SparkLayer's components in place of the elements that were just hidden.
Product list
HTML
<spark-card parent-id="{{ parentProductId }}"></spark-card>
<spark-card parent-id="{{ parentProductId }}"></spark-card>
﻿
{{ parentProductId }} the syntax for setting parent-id will vary depending on the template system used. Learn more here﻿
Product details page
HTML
<spark-pdp parent-id="{{ parentProductId }}"></spark-pdp>
<spark-pdp parent-id="{{ parentProductId }}"></spark-pdp>
﻿
﻿Learn more here﻿
Code to load SparkLayer
An example react component to load SparkLayer in a nextjs project:
JS
// SparkLayer.jsx
import { useState, useEffect } from 'react';
import Script from 'next/script';

const defaultStyles = `
// Style Spark web components to fit your design
spark-product-card {
  width: 100%;
}
spark-pdp {
  margin: 0.5em 0 1.25em;
  display: block;
}

// Set CSS vars to customise styling of elements within SparkLayer web components
:root {
  /* Set the brand styling */
  --b2b-brand-color: var(--primary);             /* Main brand colour*/
  --b2b-brand-color-hover: var(--secondary);     /* Main brand colour hover */
  --b2b-brand-font: Poppins, sans-serif;         /* Main brand font */
  --b2b-brand-font-heading: Poppins, sans-serif; /* Main brand heading font */

  /* See https://docs.sparklayer.io/sparklayer-frontend/customising-the-design
     for more variables */
}`;

const defaultOptions = {
  platform: 'shopify',
  shopify: {
    useAppProxy: false,
  },
  cartButtonSelectors: '', // CSS selector for cart button usually located in header
  accountButtonSelectors: '', // CSS selector for account button usually located in header
};

export function SparkLayer(props) {
  const {
    customer,
    authenticationMetafield,
    options,
    onLogout,
    scriptVersion,
    styles = defaultStyles,
  } = props;

  const _options = { ...defaultOptions, ...options };

  const [sparkInitialised, setSparkInitialised] = useState(false);
  const [sparkLoaded, setSparkLoaded] = useState(false);

  useEffect(() => {
    if (
      !sparkInitialised &&
      customer !== null &&
      authenticationMetafield.finished &&
      sparkLoaded &&
      !window.spark
    ) {
      const s = document.createElement('style');
      s.innerHTML = styles;
      document.head.appendChild(s);
      window.spark = window.initSpark({
        ..._options,
        onLogout,
        auth: {
          user: customer?.email,
          token: authenticationMetafield.metafield?.value,
        },
      });
      setSparkInitialised(true);
    }
  }, [customer, authenticationMetafield, sparkLoaded]);

  return customer !== null && customer.tags.includes('b2b') ? (
    <Script
      id="spark-script"
      src={`https://cdn.sparklayer.io/spark.${scriptVersion}.js`}
      onLoad={() => {
        setSparkLoaded(true);
      }}
    />
  ) : null;
}
// SparkLayer.jsx
import { useState, useEffect } from 'react';
import Script from 'next/script';

const defaultStyles = `
// Style Spark web components to fit your design
spark-product-card {
  width: 100%;
}
spark-pdp {
  margin: 0.5em 0 1.25em;
  display: block;
}

// Set CSS vars to customise styling of elements within SparkLayer web components
:root {
  /* Set the brand styling */
  --b2b-brand-color: var(--primary);             /* Main brand colour*/
  --b2b-brand-color-hover: var(--secondary);     /* Main brand colour hover */
  --b2b-brand-font: Poppins, sans-serif;         /* Main brand font */
  --b2b-brand-font-heading: Poppins, sans-serif; /* Main brand heading font */

  /* See https://docs.sparklayer.io/sparklayer-frontend/customising-the-design
     for more variables */
}`;

const defaultOptions = {
  platform: 'shopify',
  shopify: {
    useAppProxy: false,
  },
  cartButtonSelectors: '', // CSS selector for cart button usually located in header
  accountButtonSelectors: '', // CSS selector for account button usually located in header
};

export function SparkLayer(props) {
  const {
    customer,
    authenticationMetafield,
    options,
    onLogout,
    scriptVersion,
    styles = defaultStyles,
  } = props;

  const _options = { ...defaultOptions, ...options };

  const [sparkInitialised, setSparkInitialised] = useState(false);
  const [sparkLoaded, setSparkLoaded] = useState(false);

  useEffect(() => {
    if (
      !sparkInitialised &&
      customer !== null &&
      authenticationMetafield.finished &&
      sparkLoaded &&
      !window.spark
    ) {
      const s = document.createElement('style');
      s.innerHTML = styles;
      document.head.appendChild(s);
      window.spark = window.initSpark({
        ..._options,
        onLogout,
        auth: {
          user: customer?.email,
          token: authenticationMetafield.metafield?.value,
        },
      });
      setSparkInitialised(true);
    }
  }, [customer, authenticationMetafield, sparkLoaded]);

  return customer !== null && customer.tags.includes('b2b') ? (
    <Script
      id="spark-script"
      src={`https://cdn.sparklayer.io/spark.${scriptVersion}.js`}
      onLoad={() => {
        setSparkLoaded(true);
      }}
    />
  ) : null;
}
﻿
You can see an example usage of this component:
JS
// Layout.jsx
import { SparkLayer } from '../snippets/Integrations/SparkLayer';

function Layout({ ...props }) {
  // Your app should provide a way to get data for the logged in customer
  const customer = getCustomer(); 
  
  // Your app should provide a way to get Shopify metafields for the logged in customer
  const authenticationMetafield = getCustomerMetafield('sparklayer.authentication');

  return (
    <div>
      <SparkLayer
        options={{
          siteId: '',
        }}
        onLogout={() => {
          // Call function to log customer out - provided by your app
          logout();
        }}
        authenticationMetafield={authenticationMetafield}
        customer={customer}
      />
      {/* Components to render your site here */}
    </div>
  );
}

export default Layout;
// Layout.jsx
import { SparkLayer } from '../snippets/Integrations/SparkLayer';

function Layout({ ...props }) {
  // Your app should provide a way to get data for the logged in customer
  const customer = getCustomer(); 
  
  // Your app should provide a way to get Shopify metafields for the logged in customer
  const authenticationMetafield = getCustomerMetafield('sparklayer.authentication');

  return (
    <div>
      <SparkLayer
        options={{
          siteId: '',
        }}
        onLogout={() => {
          // Call function to log customer out - provided by your app
          logout();
        }}
        authenticationMetafield={authenticationMetafield}
        customer={customer}
      />
      {/* Components to render your site here */}
    </div>
  );
}

export default Layout;
﻿
For more information, please feel free to get in touch and we'd be happy to discuss our Headless solution in more detail.
Updated 30 Jul 2024
Did this page help you?
JavaScript SDK
JS SDK Docs