Frontend Integration Guide

Introduction

The process of installing the SparkLayer Frontend has been designed to be as straightforward as possible. Within the SparkLayer Dashboard, the Frontend Integration section gives you personalised instructions on how to implement the special code snippets on your website.

The process involves the following steps:

#

Installation Step

Details

1

The SparkLayer core script

A line of asynchronous JavaScript that renders the SparkLayer interfaces

2

CSS styling customisations

CSS styles that allow control over the look and feel such as colours, typefaces, and spacing

3

Product page script

This converts your existing product pages into wholesale-ready ones when customers log in

4

Advanced Configurations

This lets you extend some of the default controls such as language and how user authentication operates

Please note: the SparkLayer API integration and Platform Integration need to be completed before the SparkLayer Frontend can be enabled.

If you're installing SparkLayer on Shopify, please refer to our Shopify guide here.

The SparkLayer core script

Item

Description

What it does

This script activates all components of the SparkLayer Frontend (the SDK) and asynchronously loads it into your website to display the Product Purchasing Interface, Quick Order Interface, and My Account Interface.

Script Location

The script needs to be included within the main header of your website's source code within the <head>...</head> tags.

Code to include

You'll need your unique Site ID which can be found in the SparkLayer Dashboard My Account section.

JavaScript
JavaScript
<script>
window.sparkOptions = {
siteId: 'your-site-id',
};
</script>
<script async src="https://cdn.sparklayer.io/spark.latest.js"></script>
HTML Example
HTML Example
<head>
...
...
<script>
window.sparkOptions = {
siteId: 'your-site-id',
platform:'custom'
};
</script>
<script async src="https://cdn.sparklayer.io/spark.latest.js"></script>
</head>

If you're installing SparkLayer on a Shopify website, read our Shopify integration guide.

Additional configuration

Beyond adding the line of async JavaScript code, you'll notice a further code snippet for advanced configurations, wrapped in a <script>...<script> tag.

JavaScript
JavaScript
<script>
window.sparkOptions = {
siteId: 'your-site-id',
platform:'custom'
};
</script>

These sparkOptions configurations provide SparkLayer with additional information such as the site it's being loaded on, the eCommerce platform being used, and even the ability to overwrite core settings.

As a prerequisite, SparkLayer must require a siteId to be specified. This siteID will be supplied to you can can also be found within your SparkLayer dashboard.

Other requisites include specifying which eCommerce platform is being used; for example, if you're using Shopify, this must be included to enable the special Shopify configurations.

Please refer to our Advanced Configurations guide for more information.

CSS styling customisations

Item

Description

What it does

SparkLayer by default has a relatively neutral user interface but it's possible to update nearly all aspects of the look and feel using special CSS variables.

  • Colours

  • Typography (e.g. typefaces and font sizing)

  • Spacing (e.g. padding and margin)

  • Button styling

  • Form styling

Script Location

The CSS code can be added to your existing CSS stylesheets or placed within the main header of your website's source code (inside the<head>...</head> tags). If you're placing the CSS in your main header, remember to wrap it in <style> tags.

Knowing what can be styled

An effective way to determine the colours you want to change is to use your browser 'Inspect Element' tool. All styling for SparkLayer uses special styling codes that are proceeded with --spark- and each one can be isolated and updated.

In the Inspect Element code, you'll see something like the below. Nearly all styling elements (e.g. for a button) can be replaced and these simply needed to be added to your websites source code.

CSS example for a button
CSS example for a button
.btn, .btn-large, .btn-small {
color: var(--spark-button-raised-color,var(--spark-lightest-color,#fff));
background-color: var(--spark-button-raised-background,var(--spark-secondary-color,#125ef8));
border: var(--spark-button-border,none);
border-radius: var(--spark-button-radius,var(--spark-border-radius-button,4px));
padding: var(--spark-button-padding,.875em 1.75em);
text-transform: var(--spark-button-text-transform,none);
letter-spacing: var(--spark-button-text-letter-spacing,0);
font-weight: var(--spark-button-font-weight,400);
font-family: var(--spark-button-font-family,Poppins,sans-serif);
}

Code to include

The CSS code will vary depending on how much you want to customise, but an example is included below. Here it's updating a range of colours, fonts, and styling for buttons and tables.

Please refer to our Customising the Design guide to view all available controls

HTML Example
HTML Example
<head>
...
...
<style type="text/css">
:root {
/* Colours */
--spark-secondary-color: #5b36f5;
--spark-link-color: #5b36f5;
/* Font sizes */
--spark-pricing-fontsize: 18px;
--spark-pricing-fontsize-small: 16px;
/* Buttons */
--spark-border-radius-button: 28px;
--spark-button-font-weight: 600;
--spark-button-padding: 1rem 2.75rem;
/* Tables */
--spark-table-header-background-color: #ddd;
--spark-table-header-text-color: #222;
}
</style>
</head>

Product purchasing interface

Item

Description

What it does

Updates your existing product pages with a wholesale-ready Product Purchasing Interface. This works by 'hiding' the default layout retail customers see (i.e. B2C) and then displaying the SparkLayer version when a wholesale customer logs in. The product purchasing interface works on both your product detail pages and your product listing pages (and any location where product cards are used).

Script Location

Immediately where your standard Product Purchasing Interface is shown

Product Detail Page: Code to include

Within the file that generates the product detail page on your website (e.g. product_details.php), the first step is to isolate the code that wraps the existing Product Purchasing Interface. There is a very good reason for this; when a wholesale customer logs in, this entire wrapper needs to be hidden from view and then updated with the special Product Purchasing Interface. Without doing so, the logged in wholesale customer will see incorrect product pricing and product details.

On your B2C site, you'll need to add code to hide the existing product purchase interface

Typically this wrapper will include the following elements to be hidden:

  • Price information

  • Product variants

  • Quantity

  • Buy button

Isolating the components you need to hide

Once this has been isolated within the code, it then needs to be wrapped with a special HTML tag as below. This then tells SparkLayer to hide this from view for wholesale customers.

HTML Example
HTML Example
<div data-spark="b2c-only">
......
// Existing B2C Product Purchasing Interface
......
</div>

Finally, above this code, include the following script. This has the effect of rendering the SparkLayer Product Purchasing Interface.

SparkLayer Script
SparkLayer Script
<spark-pdp parent-id="{{ product.id }}"></spark-pdp>
SparkLayer renders a special product purchasing interface

The result in your code should look similar to this:

HTML Example
HTML Example
<spark-pdp parent-id="{{ product.id }}"></spark-pdp>
<div data-spark="b2c-only">
......
// Existing B2C Product Purchasing Interface
......
</div>

Product Listing Page: Code to include

Your website will include various locations where you display product cards. These are blocks that typically render:

  • A product image

  • A product name

  • Product pricing

  • The ability to add to cart

In much the same way as the on the product detail page (noted above), special code needs to be added to 'hide' the standard display of product pricing with the correct pricing when the customer logs in. Within the file that generates your product card details, isolate the code that renders the product pricing and wrap with the following HTML.

HTML Example
HTML Example
<div data-spark="b2c-only">
......
// Existing B2C Product Card Pricing Details
......
</div>

Above this, add the following line of code:

HTML Example
HTML Example
<spark-product-card parent-id="{{ product.id }}"></spark-product-card>

If you want to render only the wholesale pricing and hide the ability to add products to an order, you can use this line of code instead.

HTML Example
HTML Example
<spark-product-price parent-id="{{ product.id }}"></spark-product-price>

Checkout script

Shopify-only: Please refer to our guide here on how the checkout script works.

Debugging & tips

It's possible to force the SparkLayer Quick Order, SparkLayer My Account and SparkLayer Login Interfaces to always show on page load which is useful if you're trying to isolate a particular element to style or your testing API response codes. In your main site header file, simply add the following in the source code and then refresh the page.

Quick Order Interface
My Account Interface
Login Interface
Quick Order Interface
<spark-drawer initial-tab="cart"></spark-drawer>
My Account Interface
<spark-drawer initial-tab="account"></spark-drawer>
Login Interface
<spark-login></spark-login>

Remember to remove this code before you deploy your changes to production.