Advanced Configurations

Introduction

Advanced configurations allow you to customise a variety of SparkLayer settings that are used to trigger certain actions on the frontend.
These include actions such as which URL should trigger the My Account Interface (e.g. /account) to overwriting some of the default text used in the various interfaces.
If you're using SparkLayer on a third-party eCommerce platform, many of the below will be automatically enabled by default.
This guide gives an overview of what's possible and our team is happy to help if you have any specific queries.

Shopify & Shopify Plus

If you're using Shopify or Shopify Plus, you can see our advanced Shopify Configurations here.

Enabling advanced configurations

To enable the advanced configurations, a special code snippet needs to be added to the <head>...</head> of your main website header beneath the main SparkLayer JavaScript. An example is included below that defines a siteId and the eCommerce platform being used, e.g. Shopify
HTML Example
1
<head>
2
...
3
...
4
5
<script>
6
window.sparkOptions = {
7
siteId: 'your-site-id',
8
platform: 'shopify'
9
};
10
</script>
11
12
</head>
Copied!

Configuration: Language

SparkLayer supports a range of languages meaning that when users sign in, they see the correct language native to your store. By default, SparkLayer uses English and this can be adjusted by altering the core script with the addition of the language variable.

Code sample

Configuration Code
1
<script>
2
window.sparkOptions = {
3
siteId: 'your-site-id',
4
---
5
language: 'en',
6
---
7
};
8
</script>
Copied!
Language translations are supported for the following:
Variable
Language
en
English (default)
fr
French
de
German
es
Spanish
sv
Swedish
it
Italian
pt
Portugese
el
Greek
da
Danish
nl
Dutch
If you're looking to enable multiple currencies on the same store, it's possible to dynamically generate the required translations but using the below code. Behind the scenes, this will retrieve the language of the customer browsing your store and auto-populate it with the associated language variable (e.g. en, fr, de, etc)
Configuration Code
1
<script>
2
window.sparkOptions = {
3
siteId: 'your-site-id',
4
---
5
language: document.documentElement.lang,
6
---
7
};
8
</script>
Copied!
If you require a language that isn't on our list, please contact us and we can send details on how to supply translations

Configuration: Account & Cart Redirects

When SparkLayer is installed on a website, it replaces the existing My Account and Shopping Cart pages. You can learn more about how this works in our guide here.
SparkLayer has special handling whereby if a customer accesses these pages whilst logged, it will redirect them to the correct SparkLayer interface instead. For example, if they visit www.yourstore.com/account, it will instead take them to the homepage with the My Account Interface loaded.
Key
Details
accountRedirect
The URL to redirect the user to once they are logged in or if they try and access any account pages.
cartRedirect
The URL to redirect the user to when the access the /cart URL on your website

Code to include

Configuration Code
1
<script>
2
window.sparkOptions = {
3
siteId: 'your-site-id',
4
5
6
accountRedirect: {
7
urlRegex: /\/account/g,
8
goTo: '/#spark-account',
9
},
10
cartRedirect: {
11
urlRegex: /\/cart/g,
12
goTo: '/#spark-cart',
13
},
14
15
16
};
17
</script>
Copied!
If you would like to show the My Account interface or Quick Order Cart on page load, you can do so by adding #spark-account and #spark-cart to the end of the URL.
Related to the above, the SparkLayer Frontend can also be triggered by clicking buttons that may already exist on your website. For example, you may have a prominent link in your website header to the My Account area or the Shopping Cart. SparkLayer has a 'catch all' that simply updates the behaviour any time these buttons are clicked. The available configurations are as follows
Key
Details
accountButtonSelectors
If the user is logged in, the My Account interface shows. If the user is not logged in, they will be diverted back to your standard login page.
logoutButtonSelectors
This will log the user out of SparkLayer and, if authLogoutUri is set, it will then forward the user to that location (see below)
cartButtonSelectors
If the user is logged in, the Quick Order interface will be shown.

Code sample

Configuration Code
1
<script>
2
window.sparkOptions = {
3
siteId: 'your-site-id',
4
5
accountButtonSelectors: '[href="/account"], [data-spark-link=account]',
6
logoutButtonSelectors: '[href="/account/logout"], [data-spark-link=logout]',
7
cartButtonSelectors: '[href="/cart"], [data-spark-link=cart]'
8
9
};
10
</script>
Copied!

Configuration: eCommerce Platform

SparkLayer has built-in controls for specific eCommerce platforms that let you overwrite a number of different actions in the storefront experience.
Learn more about SparkLayer Platform Integrations here.
Enabling the eCommerce Platform Configuration can be done with a single line of code
Configuration Code
1
<script>
2
window.sparkOptions = {
3
siteId: 'your-site-id',
4
5
platform:'shopify'
6
7
};
8
</script>
Copied!
In the example above, Shopify has been enabled as the eCommerce platform. When adding this command, the special SparkLayer configurations are automatically added behind-the scenes. If you need to modify these, you can use the following configurations:
Key
Details
useSparkLogin
SparkLayer has a built in login modal. By default, this should be set to false to use the existing eCommerce platform login page
authLogoutUri
The URL that should trigger the user being logged out
accountRedirect
The URL that the user is redirected to upon successfully signing in
cartRedirect
The URL the user is redirected to if they access the /cart url
termsAndConditionsLink
The page the terms and conditions link in the SparkLayer Quick Order Interface should direct to

Code sample

Configuration Code
1
<script>
2
window.sparkOptions = {
3
siteId: 'your-site-id',
4
5
platform:'shopify',
6
useSparkLogin: false,
7
authLogoutUri: '/account/logout',
8
accountRedirect: {
9
urlRegex: /\/account((?!\/[login|reset]).*)/g,
10
goTo: '/',
11
},
12
cartRedirect: {
13
urlRegex: /\/cart/g,
14
goTo: '/',
15
},
16
termsAndConditionsLink: '/policies/terms-of-service'
17
18
};
19
</script>
Copied!

Configuration: Login Interface

SparkLayer has a built in Login Interface that enables your customers to quickly sign into their account via a modal overlay.
To enable this feature, simply set useSparkLogin to true
Configuration Code
1
<script>
2
window.sparkOptions = {
3
siteId: 'your-site-id',
4
5
useSparkLogin: true,
6
7
};
8
</script>
Copied!

Configuration: Show stock levels

You can optionally show live stock levels to your customers when they visit a product detail page.
Stock levels are retrieved dynamically from Shopify (or your backend system if configured) and can even be configured to display different status messages.
To enable this feature, add the following code to the SparkLayer Core Script.
Configuration Code
1
<script>
2
window.sparkOptions = {
3
siteId: 'your-site-id',
4
5
display: {
6
stock: {
7
show: true,
8
max: 50,
9
last: 5,
10
low: 15,
11
},
12
},
13
14
};
15
</script>
Copied!
You can adjust the rules of the status messages shown to customers by changing the variables in the configuration code above
Status
Details
Behaviour
max
The maximum stock level you want to show to customers. Learn more
Stock displays as "XX+ available"
last
Let your customers know that the stock level is down to its last items
Message shows as red
"Last stock"
low
Let your customers know that stock level is low
Message shows as orange
"Low stock"
If you're wanting to set a maximum stock level display, you can configure this via the SparkLayer Dashboard. For example, if you set the limit to 50, it will display as 50+ to the customer if the stock level exceeds this. Learn more

Configuration: Tiered discount percentage based off RRP

If you're using Tiered Pricing in your price lists, this will display additional information within the Product Purchasing Interface to make it clear to the customer how much they are saving based on how many units they purchase.
By default, the 'Savings' will be calculated based on the single unit price of the particular product (or variant). For example, if the single unit price is $2.00 and if you purchase 5 or more the price reduces to $1.00, the savings will display as -50%
If you'd prefer for the savings to instead be calculated off the RRP (i.e. retail price) of a product, you can enable this within the SparkLayer Core Script.
To enable this, add the following to the core script code added to the /layout/theme.liquid file within your storefront code.
Configuration Code
1
<script>
2
window.sparkOptions = {
3
siteId: 'your-site-id',
4
5
display: {
6
savingsUseRrp: true,
7
....
8
....
9
},
10
11
};
12
</script>
Copied!
Please note, you will need to specify RRP (retail prices) for your products for this configuration to work. Learn how to add RRP prices.

Configuration: Make 'Additional information' mandatory

You can force customers to complete the 'Additional information' field before proceeding to place their order.
To enable this feature, add the following code to the SparkLayer Core Script.
Configuration Code
1
<script>
2
window.sparkOptions = {
3
siteId: 'your-site-id',
4
5
displayOptions: {
6
customerReferenceRequired: true,
7
},
8
9
};
10
</script>
Copied!

Configuration: Text overwrites

SparkLayer uses 'language strings' to render the text used in the Frontend Interfaces. By default, English is fully supported, but these could be extended to any language if required (see our full list here)
Key
Details
language
This allows the language to be set (defaults to en)
translations
This overwrites any languages strings defined in the array, initially key'd by language i.e. en
showTranslations
If enabled this, shows the language string keys required to change the strings.

Updating the default text

If you're wanting to update specific text elements, it's possible to turn on a special showTranslations view that exposes specific code snippets within the SparkLayer interface. Within the SparkLayer Core Script (in file /layout/theme.liquid) simply add a new line with showTranslations: true
Configuration Code
1
<script>
2
window.sparkOptions = {
3
siteId: 'your-site-id',
4
...
5
showTranslations: true,
6
.....
7
...
8
9
};
10
</script>
Copied!
When this setting is enabled, the SparkLayer interface will then render the special language code snippets. In our example below, you can see the language code for the Product Page Interface
We recommend enabling this setting temporarily or onto a non-published theme to ensure it isn't seen by your logged in B2B customers.
To overwrite the text, you then need to add specific code snippets to the SparkLayer Core Script (in file /layout/theme.liquid). The formatting works by 'cascading' the variables. For example, in the code below, you can see how the pdp.table.price text has been included.
Configuration Code
1
<script>
2
window.sparkOptions = {
3
siteId: 'your-site-id',
4
...
5
translations: {
6
en: {
7
pdp: {
8
table: {
9
price: "Price",
10
}
11
}
12
}
13
}
14
...
15
16
};
17
</script>
Copied!
Some important items to note:
  • The variable en must be replaced with the specific language of your store (see available translations here)
  • The text overwrites must always end the line with a comma
  • If the text overwrite includes a dash (e.g. product-card), this must be specified with double quotes, i.e. "product-card"
If you require a language that isn't on our list, please contact us and we can send details on how to supply translations

Updating text that contains dynamic variables

For some text content, SparkLayer includes dynamic variables, such as pack sizing or special settings.
If you're looking to make changes to dynamic text within your Shopify store, you'll need to wrap the overwrite text within a special setting {% raw %}...{% endraw %} to ensure the dynamic variable shows correctly.
In our example below, we've shown how this works for the pack sizing text
Configuration Code
1
<script>
2
window.sparkOptions = {
3
siteId: 'your-site-id',
4
5
translations: {
6
en: {
7
global: {
8
"product-settings": {
9
{% raw %}
10
"pack-size": "This product comes in pack sizes of {{packSize}} ",
11
{% endraw %}
12
}
13
},
14
15
}
16
},
17
18
};
19
</script>
Copied!

Configuration: Prefix the price with custom text

It's possible to prefix the pricing display on a product detail page with custom language such as 'Your price':
To enable, add the following to the SparkLayer Core Script
Configuration Code
1
<script>
2
window.sparkOptions = {
3
siteId: 'your-site-id',
4
5
translations: {
6
en: {
7
pdp: {
8
price: {
9
"from-prefix": "Your Price:"
10
}
11
}
12
}
13
},
14
15
};
16
</script>
Copied!

Configuration: CSS Styles

When SparkLayer loads on a product page, it does so by replacing existing components on your store. You can learn about how this works in our guide here.
The advanced configurations can be used to define which elements are hidden or displayed by SparkLayer giving you control over what your wholesale customers do and don't see. Whilst this is useful, it is recommended to use your platform to hide and show elements as this may induce a 'flicker on page load' whilst the SparkLayer JavaScript is loaded.

Code sample

Configuration Code
1
<div data-spark="b2c-only">
2
Only shown for B2C users.
3
</div>
4
<div data-spark="b2b-only">
5
Only shown for B2B users.
6
</div>
Copied!

Adding multiple products to an order in 1-click

It's possible to create special buttons on your store that allow customers to add collections of products to an order, rather than having to add them all individually. We call these Spark Buttons.
Spark Buttons work by adding special snippets of JavaScript to your code that specify which SKUs and quantities will be added when a user clicks the button. These buttons can work anywhere on your website such as the homepage or special landing pages.
Live Demo: test this out for yourself on our B2B Demo store! Note: you'll need to be signed in first to test this feature.

Example use-cases

Spark Buttons are useful if you're looking to direct B2B customers to purchase a specific range of products. Examples could include:
  • Starter packs for brand new customers, e.g. your best-selling products
  • A curated range of products, e.g. a new season range
  • A product bundle, e.g. the top 10 products from a certain category
Once the customer adds the items to the order, they can then make changes just as they would do normally, e.g. editing quantities, removing items, etc.

Enabling Spark Buttons

Spark Buttons can be added anywhere on your store using the sample code template below. In this example, we've include two buttons with each button adding different product SKUs and different quantities.
Configuration Code
1
<!-- Example Spark Button 1 -->
2
<a href="" data-add-to-cart="">Add to order</a>
3
4
<script>
5
// <![CDATA[
6
document.querySelector('[data-add-to-cart]').addEventListener('click', function () {
7
const products = {
8
products: [
9
{
10
sku: 'SKU-123',
11
absoluteQuantity: 5,
12
},
13
{
14
sku: 'SKU-789',
15
absoluteQuantity: 5,
16
},
17
],
18
};
19
window.spark.updateCart(products);
20
});
21
// ]]>
22
</script>
23
24
25
<!-- Example Spark Button 2 -->
26
<a href="" data-add-to-cart-2="">Add to order</a>
27
28
<script>
29
// <![CDATA[
30
document.querySelector('[data-add-to-cart-2]').addEventListener('click', function () {
31
const products = {
32
products: [
33
{
34
sku: 'SKU-ABC',
35
absoluteQuantity: 10,
36
},
37
{
38
sku: 'SKU-XYZ',
39
absoluteQuantity: 10,
40
},
41
],
42
};
43
window.spark.updateCart(products);
44
});
45
// ]]>
46
</script>
Copied!
When using Spark Buttons, please note the following:
Item
Details
Inserting multiple buttons
You can insert multiple Spark Buttons on a single page providing that unique querySelectors are used. For example, in our code sample above, we've included two buttons: data-add-to-cart data-add-to-cart2
Product SKUs
For Spark Buttons to successfully add products, the product SKU must also exist within your Shopify store
Product quantities
You can specify the product quantity to add by using absoluteQuantity. If the product SKU has pack sizes configured, the quantity will automatically be rounded up.

Accessing the GraphQL API

SparkLayer uses GraphQL behind the scene and you can access the SparkLayer GraphQL API via the following method
1
const results = await window.spark.fetch("your query", {"your variables": true});
Copied!
To view the full documentation for the SparkLayer GraphQL API, click here.