Frontend Integration Guide
The process of installing the SparkLayer Frontend is designed to be as streamlined as possible, requiring only a small number of code changes to your website. Once the code has been added, your B2B customers can then log in to your website and start placing B2B orders.
The process of installing the SparkLayer frontend involves three main steps:
Adding the SparkLayer Core Script This is a JavaScript code snippet that instructs your website to display all the frontend interfaces required for SparkLayer to work.
Adding the product page scripts To display customer-specific pricing and the ability to add products to an order, special SparkLayer widgets are installed on your website's product pages.
Setting the design customisations SparkLayer has CSS configurations that allow control over the look and feel such as colours, typefaces, and spacing.
Beyond these steps, you can then apply further customisations and configurations to really tailor your B2B experience. You can learn more in Configurations as well as platform-specific recommendations in our Integrations guide.
Ready to get started? Within the SparkLayer Dashboard, the Frontend Integration section gives you personalised instructions on how to implement the special code snippets on your website.
The SparkLayer Core Script works by adding a special JavaScript code snippet into your website's theme. Once added, this then enables SparkLayer to render the special Frontend Interfaces that allow your B2B customers to place orders, manage their account, and more.
To install the SparkLayer Core Script, it simply needs to be included within the main "header" of your website's source code within the <head>...</head> tags. For Shopify, you'll need to add this to the file /layout/theme.liquid
To get started, head over to the SparkLayer Dashboard and you'll see your customised SparkLayer Core Script within the Frontend Configurations.
You'll also notice a special number at the bottom of the code shown to you, for example:
The number at the end denotes the version of SparkLayer, e.g. 1.6.x. Each time a new update is released (e.g. a new feature), this number can be updated to benefited from the latest changes. To see what's new, please see make sure to bookmark What's New!.
Please note We've recently released version 2 of SparkLayer and you can learn how to upgrade below under "Upgrading to version 2"
From a technical point of view, the Core Script provides SparkLayer with key information that controls how it works on your website.
This information includes:
Item | Details |
|---|---|
siteId | The website's unique identifier (learn more) |
platform | The eCommerce platform of the website |
language | The language to be used |
accountRedirect | The URL to redirect logged in customers to |
display | Which display configurations to enable (learn more) |
auth | The authentication details of the logged in customer |
version | The <script async sets the version (see above) |
The SparkLayer Core Script also includes the ability to add special customisations and configurations to quickly enable (or disable) specific features.
Modifying the core script follows standard JavaScript conventions and you'll need to make sure each line has the appropriate markup (e.g. a comma at the end of each line).
Available configurations You can learn more about all the available configurations on SparkLayer in our guide here.
Please note In version 2, we've introduced an improved way for you to more easily upgrade your version of SparkLayer to ensure you benefit from the latest features. In version 2, we've also launched new functionality such as managing how stock display works for your customers. You can learn more about how this works in our guide here
To upgrade your version of SparkLayer to the latest version, within the SparkLayer Dashboard, go to Settings and click Widgets (or click here).
Within the "Upgrade Core Script to V2" section, we recommend selecting the latest numeric version (e.g. 2.0.1) as your preference and then click Save.
Next, you'll need to update your website to ensure you're using the correct SparkLayer Core Script. If you're not already on version 2, your core script will look something like the below.
This needs to be updated to the new version that uses the below format:
Item | Details |
|---|---|
<site-id> | This should be replaced with your unique site ID that you can find here. |
<env> | This denotes the environment to use on SparkLayer. This should be set to live unless you're using SparkLayer in Test Mode (use test instead) |
In this example, we've adjusted this for a store with Site ID b2bstore on a live environment.
The product page scripts are the special interfaces B2B customers see when they login to your website.
There are three interfaces available:
Product Detail Interface This is show on your product detail pages and allow customers to rapidly add products to an order in a special 'table view'. Learn more
Product Card Interface This is shown anywhere a "product card" is shown such as on a product collection page or product upsell area. Learn more
Product Price Interface This allows you to display a product's B2B price anywhere on your website, whether a product detail page or product collection page. Learn more
In terms of implementing the product page scripts, there are two key steps to follow:
Hiding elements If you're installing SparkLayer on your existing retail website, you will want to ensure specific elements are hidden to ensure your B2B customers see the correct pricing and content. For example, this may include your existing retail pricing, add to cart button, variant options and the quantity selector. To do this, SparkLayer has a special tag you can add to any HTML element (see below)
Displaying the SparkLayer interfaces Special code snippets need to be added to your product pages, e.g. product detail page and product collection page. When a B2B customer logs in, these will automatically show to them and they can see prices, add items to an order, view their account, and checkout. You can learn more about the specific interfaces and how to customise them within the Frontend Interfaces guide.
SparkLayer lets you hide any element on your website by using a special HTML tag. This can be added to any HTML element that you want to be hidden from your B2B customers.
Typically elements that you would typically hide include:
- Price information
- Product variant information
- Quantity selection
- Buy button
To get started, you'll require access to the source code of your website and you'll need to locate the specific files that contain the elements you want to hide. For example, this could include editing the following pages
- A product detail page
- A product collection page
- Specific "components" that are used in multiple locations on your website
Once you've located the files, you can then use the special data-spark="b2c-only" to hide elements. This essentially adds a display: none within the CSS of your website and then hides the element when a logged in B2B customer views the page.
Please note This step requires changing the code of your website and you may want to consult an expert on how best to apply this to your website. For platform-specific guidance, please refer to Integrations
Once you've completed the step above, you can then proceed to add the special SparkLayer Frontend Interfaces.
Interface | Details |
|---|---|
Product Detail | This is shown on your product detail pages and allow customers to rapidly add products to an order. Learn more about how to add the code snippets |
Product Card | This is shown anywhere a "product card" is shown such as on a product collection page. Learn more about how to add the code snippets |
Product Price | This allows you to display a product's B2B price anywhere on your website. You can use this instead of or alongside the "Product Card" Learn more about how to add the code snippets |
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
As with the SparkLayer Core Script, the CSS code can be added to your existing CSS stylesheets or placed within the main header of your website's source code. If you're placing the CSS in your main header, remember to wrap it within the <head>...</head> tags.
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 tool, 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. Learn more in Customising the Design
Customisations available For all design customisations available please see our Customising the Design guide.
If you're in the process of setting up SparkLayer on your website, we've included a handy checklist below to make sure you've captured everything:
Core script
- You've added the SparkLayer Core Script to your website header
Product detail page
- You've added the SparkLayer Product Detail Page widget to your product detail pages.
- You've hidden any content that you don't want to show to B2B customers, such as your regular "DTC" pricing, add to cart buttons, "sticky" content that references pricing, or non-B2B content
Product cards
- You've added the SparkLayer Product Card widget to your product cards (typically shown on your collection and category pages).
- You've hidden any content that you don't want to show to B2B customers, such as your regular "DTC" pricing, add to cart buttons, "quick buy" buttons, or non-B2B content
- You've checked all areas of your website that include product cards such as the homepage and product recommendations
CSS and design
- You've added the SparkLayer CSS to your website (e.g. in the header or in a CSS file) and you've applied any styling formatting to match your branding
Cart (and Cart Drawer)
- You've checked that when clicking the "cart icon" in your website header, this triggers the My Cart Interface. If it doesn't, you need to ensure the cart is set to not trigger JavaScript for B2B customers and points to the URL /cart
General site audit
- You've checked functionality such as site search and wish-lists to ensure regular (DTC) prices are hidden (you can hide this in CSS or in the code)