JavaScript SDK

﻿
With the SparkLayer SDK, you can enhance your frontend development and create more customised experiences for your users. The SDK provides a range of straightforward functions to access data stored within SparkLayer, as well as granting access to the GraphQL API and a cart update function. These features empower developers to build more advanced and dynamic applications on top of the SparkLayer platform.
Example use-cases
The SparkLayer SDK empowers developers to build more advanced and dynamic applications on top of the SparkLayer platform. Use-cases can include:
Area
Details
Accessing Data and APIs
Provides functions to access data within SparkLayer and utilize the GraphQL API, enabling the development of advanced and dynamic applications.
Manual Initialization
Allows manual initialization of the SDK, useful in headless commerce implementations.
Customizing User Experiences
Allows calculation of pricing data, updating the shopping cart and retrieving updated cart information, customisation of the look and feel.
Product Variant Image Updating
Custom code can be added to update product images when a variant is selected, enhancing user shopping experience by providing visual feedback.
Custom Checkout Validation
Enables custom validation logic at checkout for personalized API calls to verify cart contents and manage checkout permissions based on custom rules (e.g., managing one-time discounts, product quota limits).
Adding Custom Attributes to Cart Items
Offers a method to include custom attributes with cart items, ensuring customizations are visible under the product SKU and persist through to past orders.
Please note:
The SparkLayer SDK must not be used to modify the HTML and CSS we provide via our components within your storefront. These components may be subject to update by SparkLayer which may impact any changes you make, however we do ensure our SDK is always backwards compatible. If you're unsure of the recommended use cases, our team will be happy to advise.
Manual initialisation
If you don't want SparkLayer to initialise automatically useful in headless situations, instead of setting window.sparkOptions you can manually call window.initSpark() once the script has loaded like so (requires at least version 1.0.21):
HTML
<script src="https://cdn.sparklayer.io/spark.1.0.21.js"></script>
<script>
window.spark = window.initSpark({ /* options */ })
<script>
<script src="https://cdn.sparklayer.io/spark.1.0.21.js"></script>
<script>
window.spark = window.initSpark({ /* options */ })
<script>
﻿
Example customisation
The following code snippet illustrates how to use the SparkLayer library. In this example, we're using the calculatePricingForVariant function, which takes in the parent ID, SKU, and quantity as parameters to calculate pricing data.
HTML
<script>
  window.sparkOptions = {
    siteId: "b2bshopifydemostore",
    platform: "shopify",
    // etc...
  };
</script>
<script async src="https://cdn.sparklayer.io/spark.1.0.1.js"></script>
<script>
  // Prints the following to the console: {totalPrice: 8.32, unitPrice: 4.16, currencyCode: 'gbp'}
  console.log(await window.spark.calculatePricingForVariant('6660191387839', 'MUG-MOM', 2));
  // Below is an example of updating the cart
  const products = {
    products: [
        {
            sku: 'BRACE-COLOURED',
            adjustQuantity: 3,
        },
    ],
    clearCart: false, // can be set to true to clear the cart!
  };
  console.log(await window.spark.updateCart(products)); // Returns the result of the cart changes
  console.log(await window.spark.getCart()); // Returns the updated cart
  await window.spark.updateCart({clearCart:true}); // Clears the basket
</script>
<script>
  window.sparkOptions = {
    siteId: "b2bshopifydemostore",
    platform: "shopify",
    // etc...
  };
</script>
<script async src="https://cdn.sparklayer.io/spark.1.0.1.js"></script>
<script>
  // Prints the following to the console: {totalPrice: 8.32, unitPrice: 4.16, currencyCode: 'gbp'}
  console.log(await window.spark.calculatePricingForVariant('6660191387839', 'MUG-MOM', 2));
  // Below is an example of updating the cart
  const products = {
    products: [
        {
            sku: 'BRACE-COLOURED',
            adjustQuantity: 3,
        },
    ],
    clearCart: false, // can be set to true to clear the cart!
  };
  console.log(await window.spark.updateCart(products)); // Returns the result of the cart changes
  console.log(await window.spark.getCart()); // Returns the updated cart
  await window.spark.updateCart({clearCart:true}); // Clears the basket
</script>
﻿
By viewing the spark module, you can see the functions available.
Updating the product image when a variant is selected
When using either the spark-product-card or spark-pdp widget to select a variant, the product image is not updated by default to match the selected variant. Fortunately, this behavior can be easily customised using some theme code. Here's an example of how to accomplish this with the spark-product-card widget - the process is virtually the same for spark-pdp.
Broadly, the following code changes are necessary:
Add an event listener to the spark-pdp or the spark-product-card elements for the spark-variant-change event
Within the event listener callback, show / hide product images as appropriate
Listen for the event
When the variant selector is changed, a spark-variant-change event is dispatched on the spark-product-card element. Use the following code to listen for the event.
JS
window.addEventListener("DOMContentLoaded", (event) => {
    const productCards = document.querySelectorAll("spark-product-card");
    for (productCard of productCards) {
        productCard.addEventListener("spark-variant-change", (e) => {
            console.log("spark-variant-change", e.data)
        });
    }
  },
};
window.addEventListener("DOMContentLoaded", (event) => {
    const productCards = document.querySelectorAll("spark-product-card");
    for (productCard of productCards) {
        productCard.addEventListener("spark-variant-change", (e) => {
            console.log("spark-variant-change", e.data)
        });
    }
  },
};
﻿
Please note:
Note: the event listeners can only be registered once the spark-product-card has been added to the page, which is why we suggest using the onReady option.
Show the product image
Choosing the best approach for updating variant images depends on the site's theme and markup. We've tested the following process using Shopify's Dawn theme.
The first step is to ensure that all variant images are present within the Document Object Model (DOM). If you're using Shopify, this can be done by iterating through product variants within the Liquid template that renders the product card images. You'll want to hide images for all but one variant (the first variant, which is selected by default). For the Shopify Dawn theme, the easiest way to do this is by setting the opacity to 0 (style="opacity: 0").
Next, add the data-variant-id data attribute to all variant image tags, setting it to the variant ID.
When the user selects a variant, the following properties on the event object indicate which variant was chosen:
event.detail.product.externalId - Platform (e.g., Shopify) ID of the product.
event.detail.variant.externalId - Platform (e.g., Shopify) ID of the variant.
In order to display the correct image, the callback function needs to locate the image elements for the product card within the DOM.
Here's a full working example:
JS
window.sparkOptions = {
  onReady() {
    const productCards = document.querySelectorAll("spark-product-card");
    for (productCard of productCards) {
      productCard.addEventListener("spark-variant-change", (e) => {
        const cardEl = e.target.closest(".card-wrapper");
        const variantId = e.detail.variant.externalId;

        if (!cardEl) {
          return;
        }

        // hide all variant images
        cardEl
          .querySelectorAll(`img[data-variant-id]`)
          .forEach((el) => (el.style.opacity = "0"));

        // show appropriate image
        const variantImgEl = cardEl.querySelector(
          `img[data-variant-id="${variantId}"]`,
        );

        variantImgEl && (variantImgEl.style.opacity = "1");
      });
    }
  },
};
window.sparkOptions = {
  onReady() {
    const productCards = document.querySelectorAll("spark-product-card");
    for (productCard of productCards) {
      productCard.addEventListener("spark-variant-change", (e) => {
        const cardEl = e.target.closest(".card-wrapper");
        const variantId = e.detail.variant.externalId;

        if (!cardEl) {
          return;
        }

        // hide all variant images
        cardEl
          .querySelectorAll(`img[data-variant-id]`)
          .forEach((el) => (el.style.opacity = "0"));

        // show appropriate image
        const variantImgEl = cardEl.querySelector(
          `img[data-variant-id="${variantId}"]`,
        );

        variantImgEl && (variantImgEl.style.opacity = "1");
      });
    }
  },
};
﻿
Adding custom checkout validation
Implementing custom checkout validation enables the client to create personalized calls to any API to verify the contents of the customer's cart and accordingly permit or restrict them from completing the checkout. A potential use case could be managing one-time discounts for unique customers, and utilizing an API to check if the customer has already exhausted their quota.
To set this up, assign an asynchronous function to the onCheckoutValidation spark option. The function must be asynchronous to prevent the user interface from being blocked while the API call is taking place. This function should return an array of error objects or null if there are no errors.
Here is an example of how this might work:
JS
window.sparkOptions = {
  onCheckoutValidation: async (cart) => {
    // Do API call to validate
    res = await fetch("example.com/cart-validation", {
      method: "POST",
      body: JSON.stringify(cart),
    });
    // If valid, return null.
    if (res.json().valid) {
      return null;
    }
    // If not valid, return array of error objects.
    return [
      {
        message:
          "Unable to checkout with item due to it hit product quota ordering limits.",
      },
    ];
  },
};
window.sparkOptions = {
  onCheckoutValidation: async (cart) => {
    // Do API call to validate
    res = await fetch("example.com/cart-validation", {
      method: "POST",
      body: JSON.stringify(cart),
    });
    // If valid, return null.
    if (res.json().valid) {
      return null;
    }
    // If not valid, return array of error objects.
    return [
      {
        message:
          "Unable to checkout with item due to it hit product quota ordering limits.",
      },
    ];
  },
};
﻿
In the above example, the asynchronous function onCheckoutValidation receives a cart object as a parameter. This object is then passed as a POST request to the 'cart-validation' endpoint of the example.com API. If the response from the API call is valid, the function returns null, indicating that the checkout can proceed. If the response from the API call is not valid, the function returns an array of error messages, which can then be handled by your front-end to alert the user that they cannot proceed with checkout."
Adding Custom Attributes to a Cart Item
For merchants eager to offer customizations for their products, such as custom text or any other unique requirements, SparkLayer introduces a flexible solution via a pre-cart-update hook. Once an item adorned with custom attributes is placed in the cart, these customizations become visible under the product SKU. This visibility extends to past orders, ensuring that custom attributes are consistently accessible.
Custom attributes visible in a cart item
﻿
This functionality facilitates the incorporation of custom code, allowing for seamless customization management directly from your eCommerce storefront. Below, we outline our recommended approach for implementing this feature.
Step 1: Setup the form fields for Customisation
Let's imagine your store sells shirts to your B2B customers and you need to collect additional "customisations" for your products. We can use the example of "Shirt Length" and "Shirt Fabric" as such customisations.
First, your eCommerce storefront needs to have form fields set up (e.g. an input field or select menu) where customers can enter their preferred shirt length. This form field should be clearly labelled and placed on the product page of the customisable shirt. Along with the form field for "Shirt Length," you'll also add a select menu menu for "Shirt Fabric" on the product page. This dropdown allows customers to select their preferred fabric from predefined options.
Example HTML code for the input field:
HTML
<label for="shirt-length">Shirt Length:</label>
<input
  type="text"
  id="shirt-length"
  name="shirt-length"
  placeholder="Enter preferred length in inches"
/>

<label for="shirt-fabric">Shirt Fabric:</label>
<select id="shirt-fabric" name="shirt-fabric">
  <option value="">Select Fabric</option>
  <option value="cotton">Cotton</option>
  <option value="polyester">Polyester</option>
  <option value="blend">Cotton/Polyester Blend</option>
</select>
<label for="shirt-length">Shirt Length:</label>
<input
  type="text"
  id="shirt-length"
  name="shirt-length"
  placeholder="Enter preferred length in inches"
/>

<label for="shirt-fabric">Shirt Fabric:</label>
<select id="shirt-fabric" name="shirt-fabric">
  <option value="">Select Fabric</option>
  <option value="cotton">Cotton</option>
  <option value="polyester">Polyester</option>
  <option value="blend">Cotton/Polyester Blend</option>
</select>
﻿
Step 2: Implement the preCartUpdateListener Function in spark options
Next, incorporate the preCartUpdateListener function in your Spark Options to capture the customisation inputs when the product is added to the cart. In our example above, this involves fetching the selected "shirt fabric" along with the "shirt length" and appending both as custom attributes to the product in the cart.
JS
window.sparkOptions = {
  preCartUpdateListener: (cart) => {
    if (!cart?.products?.length) {
      return cart;
    }
    // Retrieve the customisations from their respective input fields.
    const shirtLength = document.querySelector("#shirt-length")?.value;
    const shirtFabric = document.querySelector("#shirt-fabric")?.value;
    // If no customisations are provided, exit the function.
    if (!shirtLength && !shirtFabric) {
      return cart;
    }

    // Locate the product in the cart additions that requires customisation (e.g., a specific shirt SKU).
    const customShirtIndex = cart.products
      .map((p) => p.sku)
      .indexOf("SHIRT-CUSTOM");
    // If the customizable shirt is not found in the cart, exit early.
    if (customShirtIndex === -1) {
      return cart;
    }

    // Initialize customAttributes array if not already present.
    cart.products[customShirtIndex].customAttributes =
      cart.products[customShirtIndex].customAttributes || [];

    // Append 'Shirt Length' customisation, if provided.
    if (shirtLength) {
      cart.products[customShirtIndex].customAttributes.push({
        key: "Shirt Length",
        value: shirtLength,
      });
    }

    // Append 'Shirt Fabric' customisation, if provided.
    if (shirtFabric) {
      cart.products[customShirtIndex].customAttributes.push({
        key: "Shirt Fabric",
        value: shirtFabric,
      });
    }

    // Return the modified cart with the customisations included.
    return cart;
  },
};
window.sparkOptions = {
  preCartUpdateListener: (cart) => {
    if (!cart?.products?.length) {
      return cart;
    }
    // Retrieve the customisations from their respective input fields.
    const shirtLength = document.querySelector("#shirt-length")?.value;
    const shirtFabric = document.querySelector("#shirt-fabric")?.value;
    // If no customisations are provided, exit the function.
    if (!shirtLength && !shirtFabric) {
      return cart;
    }

    // Locate the product in the cart additions that requires customisation (e.g., a specific shirt SKU).
    const customShirtIndex = cart.products
      .map((p) => p.sku)
      .indexOf("SHIRT-CUSTOM");
    // If the customizable shirt is not found in the cart, exit early.
    if (customShirtIndex === -1) {
      return cart;
    }

    // Initialize customAttributes array if not already present.
    cart.products[customShirtIndex].customAttributes =
      cart.products[customShirtIndex].customAttributes || [];

    // Append 'Shirt Length' customisation, if provided.
    if (shirtLength) {
      cart.products[customShirtIndex].customAttributes.push({
        key: "Shirt Length",
        value: shirtLength,
      });
    }

    // Append 'Shirt Fabric' customisation, if provided.
    if (shirtFabric) {
      cart.products[customShirtIndex].customAttributes.push({
        key: "Shirt Fabric",
        value: shirtFabric,
      });
    }

    // Return the modified cart with the customisations included.
    return cart;
  },
};
﻿
Step 3: Developer Integration Notes
If you're looking to engage assistance in setting up customisations, we have some additional notes you can feedback to your developer:
Custom Input Field Specifications: Indicate the precise location on the product page for integrating custom input fields, providing clear instructions for the developers. For each field, detail its intended use and the appropriate input mechanism. For example, "Shirt Length" should be a numeric input, complete with minimum and maximum value constraints, whereas "Shirt Fabric" should be implemented as a select list, offering predefined options for fabric types.
preCartUpdateListener Function Implementation: Ensure the developer understands the need to capture both of the custom inputs and append them separately as custom attributes to the cart item, using JavaScript similar to the above snippet.
Testing: Request comprehensive testing across different scenarios to ensure the customisation feature works as intended, including edge cases where no input is provided or input is invalid.
Line Item File Attachments
To add a file attachment as a line item customization, you will need to do 2 things:
Add the spark-file-upload-field component (for selecting the file) into your website source code
Add some code to the preCartUpdateListener in sparkOptions
Using the spark-attachment component
JS
<spark-file-upload-field id="spark-attachment" allowed-extensions='["png", "jpg", "jpeg"]'></spark-file-upload-field>
<spark-file-upload-field id="spark-attachment" allowed-extensions='["png", "jpg", "jpeg"]'></spark-file-upload-field>
﻿
All properties:
Property
Description
allowed-extensions
A list of file extensions to allow to be uploaded (in JSON format). By default, this will allow most common file extensions
max-file-size
The maximum size of file that can be uploaded, in bytes
max-files
The maximum number of files that can be uploaded
required
Whether a file must be uploaded
This component dispatches the following events:
spark-file-attachment-changed - when the list of files changes (i.e. a new file is added, or one is removed)
spark-file-attachment-failed - when a file fails to upload
You can add listeners for these events with the following JavaScript:
JS
window.addEventListener('spark-file-attachment-changed', (e) => {
  // e.detail is an array of the file details in the following format:
  // {
  //   fileSize: number,
  //   fileName: string,
  //   gid: string,
  // }

  // Handle files
});

window.addEventListener('spark-file-attachment-failed', (e) => {
  // e.detail format:
  // {
  //   fileSize: number,
  //   fileName: string,
  //   errorCode: string,
  // }
  //
  // errorCode can be one of the following:
  // - "unsupported-file-type"
  // - "file-too-large"
  // - "default"

  // Handle failed file...
});
window.addEventListener('spark-file-attachment-changed', (e) => {
  // e.detail is an array of the file details in the following format:
  // {
  //   fileSize: number,
  //   fileName: string,
  //   gid: string,
  // }

  // Handle files
});

window.addEventListener('spark-file-attachment-failed', (e) => {
  // e.detail format:
  // {
  //   fileSize: number,
  //   fileName: string,
  //   errorCode: string,
  // }
  //
  // errorCode can be one of the following:
  // - "unsupported-file-type"
  // - "file-too-large"
  // - "default"

  // Handle failed file...
});
﻿
Example
On your product page:
HTML
{%- if customer.tags contains 'b2b' -%}
  <div>
    <h4 style="margin-bottom: 8px;">Design</h4>
    <spark-file-upload-field
      allowed-extensions='["png", "jpg", "jpeg"]'
      max-files="2"
      id="shirt-design-upload-button"
    ></spark-file-upload-field>
  </div>

  <!-- Input required to store the GID for use in `preCartUpdateListener` -->
  <input id="shirt-design" type="hidden" name="Front Design">

  <script>
    const uploadElem = document.querySelector("#shirt-design-upload-button");
    uploadElem.addEventListener('spark-file-attachment-changed', (e) => {
      // Set GID for use in `preCartUpdateListener`
      const fileUpload = document.querySelector("#shirt-design");

      // Convert the list of files into a list of GIDs and turn that into a JSON string
      fileUpload.value = e.detail ? JSON.stringify(e.detail.map(f => f.gid)) : null;
    });
  </script>
{%- endif -%}
{%- if customer.tags contains 'b2b' -%}
  <div>
    <h4 style="margin-bottom: 8px;">Design</h4>
    <spark-file-upload-field
      allowed-extensions='["png", "jpg", "jpeg"]'
      max-files="2"
      id="shirt-design-upload-button"
    ></spark-file-upload-field>
  </div>

  <!-- Input required to store the GID for use in `preCartUpdateListener` -->
  <input id="shirt-design" type="hidden" name="Front Design">

  <script>
    const uploadElem = document.querySelector("#shirt-design-upload-button");
    uploadElem.addEventListener('spark-file-attachment-changed', (e) => {
      // Set GID for use in `preCartUpdateListener`
      const fileUpload = document.querySelector("#shirt-design");

      // Convert the list of files into a list of GIDs and turn that into a JSON string
      fileUpload.value = e.detail ? JSON.stringify(e.detail.map(f => f.gid)) : null;
    });
  </script>
{%- endif -%}
﻿
In window.sparkOptions:
JS
window.sparkOptions = {
  preCartUpdateListener: (cart) => {
    if (!cart?.products?.length) {
      return cart;
    }

    // Retrieve the customisations from their respective input fields.
    const elem = document.querySelector("#shirt-design");
    const file = elem?.value;
    // If no customisations are provided, exit the function.
    if (!file) {
      return cart;
    }

    // Locate the product in the cart additions that requires customisation (e.g., a specific shirt SKU).
    const customShirtIndex = cart.products
      .map((p) => p.sku)
      .indexOf("SHIRT-CUSTOM");
    // If the customizable shirt is not found in the cart, exit early.
    if (customShirtIndex === -1) {
      return cart;
    }

    // Initialize customAttributes array if not already present.
    cart.products[customShirtIndex].customAttributes =
      cart.products[customShirtIndex].customAttributes || [];

    // Append 'Custom Design' customisation, if provided.
    cart.products[customShirtIndex].customAttributes.push({
      key: elem.name,
      value: file,
    });

    // Return the modified cart with the customisations included.
    return cart;
  } }
window.sparkOptions = {
  preCartUpdateListener: (cart) => {
    if (!cart?.products?.length) {
      return cart;
    }

    // Retrieve the customisations from their respective input fields.
    const elem = document.querySelector("#shirt-design");
    const file = elem?.value;
    // If no customisations are provided, exit the function.
    if (!file) {
      return cart;
    }

    // Locate the product in the cart additions that requires customisation (e.g., a specific shirt SKU).
    const customShirtIndex = cart.products
      .map((p) => p.sku)
      .indexOf("SHIRT-CUSTOM");
    // If the customizable shirt is not found in the cart, exit early.
    if (customShirtIndex === -1) {
      return cart;
    }

    // Initialize customAttributes array if not already present.
    cart.products[customShirtIndex].customAttributes =
      cart.products[customShirtIndex].customAttributes || [];

    // Append 'Custom Design' customisation, if provided.
    cart.products[customShirtIndex].customAttributes.push({
      key: elem.name,
      value: file,
    });

    // Return the modified cart with the customisations included.
    return cart;
  } }
﻿
Integrating Google Analytics with SparkLayer SDK
Enabling Google Analytics or GTM
To enable GA4 or GTM within your SparkLayer setup, configure the analytics option in your sparkOptions. You can specify multiple analytics providers, each with their respective event handlers and the events you wish to track.
JS
window.sparkOptions = {
  // ... other SparkLayer options ...

  analytics: {
    providers: [
      {
        handler: 'ga', // Use 'ga' for Google Analytics
        events: {
          addToCart: true,
          cartUpdate: true,
          shoppingListSave: true,
          shoppingListLoad: true,
          shoppingListDelete: true,
          csvUpload: true,
          quickAdd: true,
          finalStageCheckout: true,
          shippingUpdate: true,
          beginCheckout: true,
          purchase: true,
          viewCart: true
        }
      },
      {
        handler: 'gtm', // Use 'gtm' for Google Tag Manager
        events: {
          addToCart: true,
          cartUpdate: true,
          shoppingListSave: true,
          shoppingListLoad: true,
          shoppingListDelete: true,
          csvUpload: true,
          quickAdd: true,
          finalStageCheckout: true,
          shippingUpdate: true,
          beginCheckout: true,
          purchase: true,
          viewCart: true
        }
      },
      {
        handler: function(eventName, eventParam) {
          console.log('Event fired to custom provider:', eventName, eventParam);
          // Implement your custom analytics logic here
        },
        events: {
          addToCart: true,
          cartUpdate: true,
          shoppingListSave: true,
          shoppingListLoad: true,
          shoppingListDelete: true,
          csvUpload: true,
          quickAdd: true,
          finalStageCheckout: true,
          shippingUpdate: true,
          beginCheckout: true,
          purchase: true,
          viewCart: true
        }
      }
    ]
  }
};
window.sparkOptions = {
  // ... other SparkLayer options ...

  analytics: {
    providers: [
      {
        handler: 'ga', // Use 'ga' for Google Analytics
        events: {
          addToCart: true,
          cartUpdate: true,
          shoppingListSave: true,
          shoppingListLoad: true,
          shoppingListDelete: true,
          csvUpload: true,
          quickAdd: true,
          finalStageCheckout: true,
          shippingUpdate: true,
          beginCheckout: true,
          purchase: true,
          viewCart: true
        }
      },
      {
        handler: 'gtm', // Use 'gtm' for Google Tag Manager
        events: {
          addToCart: true,
          cartUpdate: true,
          shoppingListSave: true,
          shoppingListLoad: true,
          shoppingListDelete: true,
          csvUpload: true,
          quickAdd: true,
          finalStageCheckout: true,
          shippingUpdate: true,
          beginCheckout: true,
          purchase: true,
          viewCart: true
        }
      },
      {
        handler: function(eventName, eventParam) {
          console.log('Event fired to custom provider:', eventName, eventParam);
          // Implement your custom analytics logic here
        },
        events: {
          addToCart: true,
          cartUpdate: true,
          shoppingListSave: true,
          shoppingListLoad: true,
          shoppingListDelete: true,
          csvUpload: true,
          quickAdd: true,
          finalStageCheckout: true,
          shippingUpdate: true,
          beginCheckout: true,
          purchase: true,
          viewCart: true
        }
      }
    ]
  }
};
﻿
Configuration details
providers: An array of analytics providers you wish to integrate. Each provider object can define a handler and the specific events to track.
Provider Options
Provider Type
Description
'ga'
Integrates with Google Analytics (GA4). This works best when using Shopify's GA4 solution.
'gtm'
Integrates with Google Tag Manager.
function
Allows for a custom analytics handler. Use this to integrate with other analytics platforms or to implement bespoke tracking logic.
Available Events
Event Name
Description
addToCart
Triggered when a product is added to the cart.
cartUpdate
Fired when the cart is updated (e.g., quantity changes, item removals).
shoppingListSave
Occurs when a shopping list is saved.
shoppingListLoad
Occurs when a shopping list is loaded.
shoppingListDelete
Occurs when a shopping list is deleted.
csvUpload
Triggered when a CSV file is uploaded.
quickAdd
Fired during quick add actions.
finalStageCheckout
Occurs at the final stage of the checkout process.
shippingUpdate
Fired when shipping details are updated during the checkout.
beginCheckout
Triggered when the checkout process begins.
purchase
Occurs upon successful purchase completion.
viewCart
Fired when the cart is viewed.
Custom Analytics Provider
If you need to integrate with an analytics service not natively supported by SparkLayer, you can define a custom handler function. This function receives the event name and parameters, allowing you to implement any tracking logic as needed.
JS
{
  handler: function(eventName, eventParam) {
    // Example: Send event data to a custom analytics service
    fetch('https://your-analytics-endpoint.com/track', {
      method: 'POST',
      headers: {
        'Content-Type': 'application/json'
      },
      body: JSON.stringify({
        event: eventName,
        parameters: eventParam
      })
    })
    .then(response => response.json())
    .then(data => {
      console.log('Custom analytics event tracked:', data);
    })
    .catch(error => {
      console.error('Error tracking custom analytics event:', error);
    });
  },
  events: {
    addToCart: true,
    cartUpdate: true,
    // ... other events ...
  }
}
{
  handler: function(eventName, eventParam) {
    // Example: Send event data to a custom analytics service
    fetch('https://your-analytics-endpoint.com/track', {
      method: 'POST',
      headers: {
        'Content-Type': 'application/json'
      },
      body: JSON.stringify({
        event: eventName,
        parameters: eventParam
      })
    })
    .then(response => response.json())
    .then(data => {
      console.log('Custom analytics event tracked:', data);
    })
    .catch(error => {
      console.error('Error tracking custom analytics event:', error);
    });
  },
  events: {
    addToCart: true,
    cartUpdate: true,
    // ... other events ...
  }
}
﻿
Configuring redirect on login
To configure redirection within SparkLayer, you need to include the spark-redirect.js script in your HTML. This script should be placed outside of the {%- if customer.metafields.sparklayer.authentication -%} conditional block in order for it to be picked up even if the user isn't authenticated.
HTML
<script async src="https://cdn.sparklayer.io/spark-redirect.js"></script>
<script async src="https://cdn.sparklayer.io/spark-redirect.js"></script>
﻿
By default, if a user is not authenticated, they will be redirected to the /account/login page. You can customize this login path by setting the window.sparkRedirectLoginPath variable before including the script:
HTML
<script>
    window.sparkRedirectLoginPath = "/account/login";
</script>
<script async src="https://cdn.sparklayer.io/spark-redirect.js"></script>
<script>
    window.sparkRedirectLoginPath = "/account/login";
</script>
<script async src="https://cdn.sparklayer.io/spark-redirect.js"></script>
﻿
Some links (for example, the 'View Order' button in certain emails) will trigger specific functionality on sparklayer once the user has logged in. In order for this to work, you need to add the spark-redirect.js script above in addition to the core spark script.
Area	Details
Accessing Data and APIs	Provides functions to access data within SparkLayer and utilize the GraphQL API, enabling the development of advanced and dynamic applications.
Manual Initialization	Allows manual initialization of the SDK, useful in headless commerce implementations.
Customizing User Experiences	Allows calculation of pricing data, updating the shopping cart and retrieving updated cart information, customisation of the look and feel.
Product Variant Image Updating	Custom code can be added to update product images when a variant is selected, enhancing user shopping experience by providing visual feedback.
Custom Checkout Validation	Enables custom validation logic at checkout for personalized API calls to verify cart contents and manage checkout permissions based on custom rules (e.g., managing one-time discounts, product quota limits).
Adding Custom Attributes to Cart Items	Offers a method to include custom attributes with cart items, ensuring customizations are visible under the product SKU and persist through to past orders.
Property	Description
allowed-extensions	A list of file extensions to allow to be uploaded (in JSON format). By default, this will allow most common file extensions
max-file-size	The maximum size of file that can be uploaded, in bytes
max-files	The maximum number of files that can be uploaded
required	Whether a file must be uploaded
Provider Type	Description
'ga'	Integrates with Google Analytics (GA4). This works best when using Shopify's GA4 solution.
'gtm'	Integrates with Google Tag Manager.
function	Allows for a custom analytics handler. Use this to integrate with other analytics platforms or to implement bespoke tracking logic.
Event Name	Description
addToCart	Triggered when a product is added to the cart.
cartUpdate	Fired when the cart is updated (e.g., quantity changes, item removals).
shoppingListSave	Occurs when a shopping list is saved.
shoppingListLoad	Occurs when a shopping list is loaded.
shoppingListDelete	Occurs when a shopping list is deleted.
csvUpload	Triggered when a CSV file is uploaded.
quickAdd	Fired during quick add actions.
finalStageCheckout	Occurs at the final stage of the checkout process.
shippingUpdate	Fired when shipping details are updated during the checkout.
beginCheckout	Triggered when the checkout process begins.
purchase	Occurs upon successful purchase completion.
viewCart	Fired when the cart is viewed.
Get Sync Logging status errors
Headless