JavaScript SDK

<img src="https://www.sparklayer.io/assets/images/docs/banner-sdk.jpg?v=45" style="display: block; width: 100%;">
<img src="https://www.sparklayer.io/assets/images/docs/banner-sdk.jpg?v=45" style="display: block; width: 100%;">
﻿
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.
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',
            deltaQuantity: 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
</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',
            deltaQuantity: 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
</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 customized 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-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.sparkOptions = {
  onReady() {
    const productCards = document.querySelectorAll("spark-product-card");
    for (productCard of productCards) {
      productCard.addEventListener("spark-variant-change", (e) => {
        // Place code to update product image here (example below)
      });
    }
  },
};
window.sparkOptions = {
  onReady() {
    const productCards = document.querySelectorAll("spark-product-card");
    for (productCard of productCards) {
      productCard.addEventListener("spark-variant-change", (e) => {
        // Place code to update product image here (example below)
      });
    }
  },
};
﻿
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."
Updated 04 Sep 2023
Did this page help you?
Get Purchase
Headless
Docs powered by
Archbee
TABLE OF CONTENTS
Manual initialisation
Example customisation
Updating the product image when a variant is selected
Listen for the event
Show the product image
Adding custom checkout validation