Frontend configuration
Checkout frontend configuration includes the following options:
- API Credentials enable connection
- Assets images and icons not related to products
- Carriers add and edit
- General Configuration
- dynamic (input) fields (contact details)
- currency, dates and format
- links
- notifications
- payments
- styles
- shipment and delivery
- tracking
- Hosts add new
- Whitelist domains and routes
- Loyalty programs
- Routes and domains for desktop, mobile, and apps
- Styles add custom CSS
- Best practices for integrating the checkout Webcomponent
Checkout is configured on the local shop level.
Configure Checkout in the SCAYLE Panel
- In the SCAYLE Panel, go to
Shops > [Shop] > Storefront > Checkout Settings > Checkout Frontend Configuration.
API Credentials
Change the API credentials for service costs and risk assessment.
SCAYLE Checkout enables you to make API connections for service costs and risk assessment.
Enable API connection in the SCAYLE Panel
- Go to
Shops > [Shop] > Storefront > Checkout Settings > Checkout Frontend Configuration > API Credentials.
- Add the Hostname and Username.
- Click SAVE.
Assets
Manage the static assets such as images and icons not related to products.
The assets have to be in SVG format and should not exceed 100 KB in size.
Add assets to the Checkout in the SCAYLE Panel
- Go to
Shops > [Shop] > Storefront > Checkout Settings > Checkout Frontend Configuration > Assets.
- Hover over the asset you want to replace to show the pen icon.
- Click the pen icon to upload a new asset.
- Click SAVE.
See Theming and Assets for information how to manage assets.
Carriers
See Carriers.
General Configuration
Configure features and set client-specific settings or validation rules of the Checkout Frontend.
The General Configuration page contains the config.json
file where you can customize properties. For details, see the following pages:
- compatibility fixes
- enable/disable features
- define currency and format
- customize shipping & delivery according to your requirements
- customize notifications
- address forms and field validation: configure address forms and set constraints on fields (e.g., min/max length, input format)
- setup dynamic fields (phone number, birthdate, checkboxes, etc.)
- specify external links (e.g. terms and conditions, privacy policy, etc.)
Compatibility fixes
Notifications
For notifications, it is necessary to know the height of the header on both desktop and mobile. Since all tenants will not have the same class names to query for the height, we have set a direct pixel value in the configuration below header
. The type is a number
:
Parameter | Description | Data Type | Possible Values |
---|---|---|---|
desktopHeight | height of the header on desktop in px | number | e.g. 152 |
mobileHeight | height of the header on mobile devices in px | number | e.g. 73 |
We discourage using this method of setting the header offset due to issues with fixed headers and scrolling. Instead, it is advised to inject the header-element
directly into the Webcomponent.
You can find an example of the header size properties in JSON format below:
"header": {
"desktopHeight": 152,
"mobileHeight": 73
},
Iframe Authentication
There are several scenarios where some extra logic needs to be added due to the fact the authentication is done with an iframe.
Make password reset notification visible
This event listener needs to be added in the storefront to enable scrolling to the top of the page on mobile to make sure the success notification is visible after a password reset.
window.addEventListener("message", (e) => {
if (e.data.type === "scroll") {
window.scrollTo(e.data.options);
}
});
Scroll to top on "Create an account" button from Guest authentication
In order to make the scrollIntoView
feature to work for the embedded iframe version of the authentication, the following event listener needs to be added.
window.addEventListener("message", (event) => {
if (event.data.type === 'scrollToElement') {
const elementId = event.data.elementId;
const behavior = event.data.behavior;
const block = event.data.block;
const element = document.getElementById(elementId);
if (element) {
element.scrollIntoView({ block, behavior });
}
}
});
The config.json
file consists of a set of root configurations that apply across all shop countries (e.g., activation of guest Checkout). It also includes areas to add country and locale specific overwrites. In other words, you have the same options available on the root level and define locale/country level differences.
Special checkout features (such as a guest checkout or address book) can be easily on and off using the following parameters (in the features
object). Some features cannot only be enabled or disabled, but also take additional configuration. The code snippets listed within the feature explanation tabs below represent the default values.
When this feature is enabled, breadcrumbs will be visible at the top of the checkout that indicate which step the user is on.
Dynamic fields
In the configuration, input fields (e.g. birth date and phone number) as well as checkboxes (e.g. newsletter sign up, terms and conditions / privacy policy consent) are considered dynamic fields.
Use either the provided JSON file or the UI (Beta) to configure dynamic fields.
Access JSON file to configure dynamic fields in the SCAYLE Panel
- Go to
Shops > [Shop] > Storefront > Checkout Settings > Checkout Frontend Configuration > General Configuration.
The configuration key for each field is composed like this: dynamicFields.{area}.{field}
dynamicFields.shippingAddress.phoneNumber
Dynamic fields can appear in the following areas:
Registration
{
"dynamicFields": {
"register": {
...
}
}
}
Checkout as Guest
{
"dynamicFields": {
"guest": {
...
}
}
}
Shipping Addres
{
"dynamicFields": {
"shippingAddress": {
...
}
}
}
Billing Address
{
"dynamicFields": {
"billingAddress": {
...
}
}
}
Collection Point
{
"dynamicFields": {
"collectionPoint": {
...
}
}
}
Payment Options
{
"dynamicFields": {
"paymentOptions": {
...
}
}
}
Payment Step (After Payment Options)
{
"dynamicFields": {
"payment": {
...
}
}
}
Payment Step (Below Mobile Basket, Above 'Pay Now' Button
{
"dynamicFields": {
"paymentBelowMobileBasket": {
...
}
}
}
Birth Date
{
"birthDate": {
"required": true,
"minAge": 18
}
}
Phone number
required
:true
|false
- Specify if the field is required or optional
mobileOnly
:true
|false
- Used to only allow mobile phone numbers
restrictCountry
:true
|false
- Used to restrict the field to phone numbers from the current country (preventing foreign phone numbers)
Even if the phone number field is not restricted to the current country, the phone number field is biased towards the current country. If no phone number country code (e.g. 0049
/+49
for DE
) is entered, the field will assume that it is a number from the current country. However, if you enter a phone number beginning with a country code and restrictCountry
is not true
, it will be accepted.
{
"phoneNumber": {
"required": true,
"mobileOnly": true,
"restrictCountry": false
}
}
Logistics Phone Number
required
:true
|false
- Specify if the field is required or optional
mobileOnly
:true
|false
- Used to only allow mobile phone numbers
restrictCountry
:true
|false
- Used to restrict the field to phone numbers from the current country (preventing foreign phone numbers)
Even if the phone number field is not restricted to the current country, the phone number field is biased towards the current country. If no phone number country code (e.g. 0049
/+49
for DE
) is entered, the field will assume that it is a number from the current country. However, if you enter a phone number beginning with a country code and restrictCountry
is not true
, it will be accepted.
{
"logisticsPhoneNumber": {
"required": true,
"mobileOnly": true,
"restrictCountry": false
}
}
Tax ID
- The general field validation properties can be used (see Field Validation).
This is used if there is a need to set a tax id, usually for bigger orders or to comply with a certain country's laws.
{
"taxId": {
"required": true
}
}
Carrier customer ID
The general field validation properties can be used (see Field Validation).
This is used to set a carrier specific customer ID (e.g. DHL Postnummer)
{
"carrierCustomerId": {
"required": true,
"minLength": 6,
"maxLength": 10,
"format": "^\\d+$"
}
}
Checkboxes
required
is used to specify if the field is required or optional.name
is used to specify the checkbox name. For newsletter sign up set this to newsletterSignUp to enable the respective API handling.i18nKeys.label
is used to specify the translation key of the checkbox label.i18nKeys.headline
is used to specify the translation key of the checkbox headline (optional, only needs to be set, if there should be a headline).
Any number of Checkboxes (e.g. newsletter sign up, terms and conditions / privacy policy consent, ...)
{
"checkboxes": [
{
"name": "newsletterSignUp",
"i18nKeys": { "label": "auth.newsletterSignUp" }
}
]
}
Texts
Available Properties
name
is used to specify the text name.i18nKeys.label
is used to specify the translation key of the text.i18nKeys.headline
is used to specify the translation key of the text headline (optional, only needs to be set, if there should be a headline).
Any number of simple Text Paragraphs (e.g. legal hints, ...)
{
"texts": [{ "name": "term_conditions_info", "i18nKeys": { "label": "custom1" } }]
}
Conditions
Sample configuration
{
"register": {
"checkboxes": [
{
"name": "newsletterSignUp",
"i18nKeys": { "label": "auth.newsletterSignUp" }
}
]
},
"guest": {
"checkboxes": [
{
"name": "newsletterSignUp",
"i18nKeys": { "label": "auth.newsletterSignUp" }
}
]
},
"shippingAddress": {
"birthDate": {
"required": true,
"minAge": 18
},
"phoneNumber": {
"required": true
},
"logisticsPhoneNumber": {
"required": true,
"conditions": {
"enabled": { "carrierGroupKey": ["dhl"] }
}
}
},
"collectionPoint": {
"carrierCustomerId": {
"required": true,
"format": "^//d+$",
"conditions": {
"enabled": { "carrierGroupKey": ["dhl"] }
}
}
},
"paymentOptions": {
"birthDate": {
"required": true,
"minAge": 18,
"conditions": {
"enabled": { "paymentOptionKey": ["computop_creditcard"] }
}
},
"phoneNumber": {
"required": true,
"conditions": {
"enabled": { "paymentOptionKey": ["klarna_paynow_direct_bank_transfer"] }
}
}
},
"payment": {
"checkboxes": [
{
"name": "newsletterSignUp",
"i18nKeys": { "label": "auth.newsletterSignUp" }
},
{
"name": "termsAndPrivacy",
"required": true,
"i18nKeys": { "label": "payment.termsAndPrivacy" }
}
]
}
}
Links
The links
section specifies common links (e.g., to terms and conditions, privacy policy, etc.) that can be referenced in the translation strings of dynamic checkboxes and texts (see Dynamic Fields). links
is an array consisting of objects with a key
and a link
property.
Parameter | Description | Data Type | Possible Values |
---|---|---|---|
key | unique translation key for Crowdin project | string | Crowdin translation key |
link | the hyperlink that needs to open | string | URL |
Use key backToShop
to customize the "Back To Shop" link on the "Empty Basket" and "Payment Confirmation Pending" pages.
Use key basket
to provide the URL of the basket page. If this link is provided, the basket page will appear as an extra step in the breadcrumbs.
Example
"links": [
{
"key": "privacyPolicy",
"link": "https://www.aboutyou.de/datenschutz"
}
],
In the translation strings of dynamic checkboxes and texts (see Dynamic Fields) the links can be referenced using this tag syntax:
I accept the <privacyPolicyLink>Privacy Policy</privacyPolicyLink>.
For the tag name, use the link's key
suffixed with Link
. For example, if the key is privacyPolicy
it can be accessed as <privacyPolicyLink>...</privacyPolicyLink>
as in the example above. If it is someThing
it can be accessed as <someThingLink>...</someThingLink>
.
Hosts
The following host is created for the new shop:
Attribute | Value |
---|---|
Host domain | {TENANT_ENV}.checkout.api.{DOMAIN_NAME} |
Device | desktop |
Basic Authentication | disabled |
Is Generic | enabled* |
{TENANT_ENV}: Configured tenant environment name
{DOMAIN_NAME}: Configured domain name
&#xNAN;*: If a non generic host for the tenant doesn’t already exist, then create another host with the default data, except with Is Generic
disabled.
Add New Host
To add a new host in the SCAYLE Panel:
- Go to
Shops > Shop > Storefront > Checkout Settings > Checkout Frontend Configuration
. - Click Add New Host.
- Under General Information, set the Host domain, Device, Theme name, and Theme version.
- Set Basic Authentication or Is Generic.
- Click Save.
Whitelist domains and paths
Once the host configuration is saved, you can add or edit whitelist domains and paths.
In production the shop domain will be whitelisted with and without www
with path *
.
In non-production environment a new record that allows every domain (*
) is added with path *
. If a non generic host was added, another record will be added with whitelisted domain *
and path *
.
Add domains and paths to the whitelist in the SCAYLE Panel
- Go to
Shops > Shop > Storefront > Checkout Settings > Checkout Frontend Configuration > General Configuration > Hosts.
- Select the tab Whitelisted Hosts. You can whitelist specific origin domains or allow all by adding an asterisk (*).
- Click Save Changes.
Loyalty Program
See Loyalty Program for information how to customize configure loyalty programs.
Routes & Domains
Configure routes and domains for desktop, mobile, and apps.
- Go to
Shops > Shop > Storefront > Checkout Settings > Checkout Frontend Configuration> Routes & Domains.
- Click Save Changes.
Separate settings can be made for desktop and mobile.
Under Configuration, the toggle buttons allow you to:
- Include the shop ID on the redirect
- Provide login state notification
- Provide logout state notification
Routes
Under Routes, you can set the paths for different areas of your shop such as contact, password reset, order success, etc.
Add routes in the SCAYLE Panel
- Go to
Shops > Shop > Storefront > Checkout Settings > Checkout Frontend Configuration > General Configuration > Routes.
- Set the new path for the required area of your shop.
- Click Save Changes to save the configuration and fields.
Attribute | Value |
---|---|
Include Shop Id On Redirect | disabled |
Provide Login State Notification | enabled |
Provide Logout State Notification | enabled |
Default routes
The following routes are added for desktop, mobile and app by default:
Attribute | Value |
---|---|
Account Area | /account |
Back | /back |
Bank Data | /bank-data |
Cancellation | /cancellation |
Contact | /contact |
General FAQ | /faq |
Imprint | /imprint |
Logout | /logout |
Newsletter Unsubscription | /newsletter/unsubscribe |
Order Success | /order/success |
Password Reset | /password/reset?hash={hash} |
Payment FAQ | /faq/payments |
Privacy Statement | /privacy |
Product Link | /product- |
Shipping Costs | /shipping-costs |
Terms Of Service | /terms-of-service |
Terms Of Use | /terms-of-use |
Domains
You can set separate URLs for the CDN (and Static CDN), Shop, and Checkout.
Add domains in the SCAYLE Panel
- Go to
Shops > Shop > Storefront > Checkout Settings > Checkout Frontend Configuration > General Configuration > Domains.
- Set the new URL.
- Click Save Changes.
Check Content Delivery Network URLs in the User Guide for details how to add a CDN URL.
Styles
You can change the styling directly in the SCAYLE Panel and save changes. The changes will be visible in approx. 1 min. in all of your shops.
See Theming and Assets for information how to customize your Checkout Frontend's look and feel.
Best practices
Integrating the checkout Webcomponent
To ensure the fastest possible loading time of the checkout Webcomponent, we have compiled a list of suggestions for developers to adhere to.
Load the JavaScript bundle as soon as possible with the highest priority
Render the HTML tag for the Webcomponent on the server and inject the checkout JavaScript as close as possible to it, as well as using preloading so it gets the highest priority.
If no fetchPriority attribute is explicitly set, the browser will determine this on its own, sometimes putting it lower in the loading sequence than necessary. If this is the case, you can set it to high when loading the script to force this on most browsers.
Any other scripts such as Google Analytics and other tracking services should be prioritized after the loading of the checkout.
Only load third-party scripts that are necessary and actively used in the Checkout
Each additional script adds weight to the page, increasing loading times and the chance of errors. By loading only scripts essential for the Checkout functionality, you streamline the process, improve page speed, and create a smoother, more efficient checkout experience for your users.
Ensure that static assets served on production are minified
Minification removes unnecessary characters, whitespace, and comments, significantly reducing file sizes. This leads to faster downloads, quicker page rendering, and ultimately, a better user experience.
Keep loading animations to a small file size by using animated CSS and SVG files
If using a custom loading animation while waiting for the checkout to load, it is recommended to keep the file size to a minimum to avoid adding further weight to the loading process. SVG files and CSS animations are a good lightweight solution to this problem.
Checkout CDN assets such as the JavaScript bundle, icons and CSS should have an optimized caching policy that is set up and maintained by SCAYLE.