docs
  1. SCAYLE Resource Center
  2. Configure
  3. Frontend configuration

Frontend configuration

Checkout frontend configuration includes the following options:

Checkout is configured on the local shop level.

Configure Checkout in the SCAYLE Panel

  1. In the SCAYLE Panel, go to Shops > [Shop] > Storefront > Checkout Settings > Checkout Frontend Configuration.

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

  1. Go to Shops > [Shop] > Storefront > Checkout Settings > Checkout Frontend Configuration > API Credentials.
  2. Add the Hostname and Username.
  3. 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

  1. Go to Shops > [Shop] > Storefront > Checkout Settings > Checkout Frontend Configuration > Assets.
  2. Hover over the asset you want to replace to show the pen icon.
  3. Click the pen icon to upload a new asset.
  4. 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:

ParameterDescriptionData TypePossible Values
desktopHeightheight of the header on desktop in pxnumbere.g. 152
mobileHeightheight of the header on mobile devices in pxnumbere.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

  1. 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" }
            }
        ]
    }
}

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.

ParameterDescriptionData TypePossible Values
keyunique translation key for Crowdin projectstringCrowdin translation key
linkthe hyperlink that needs to openstringURL

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:

AttributeValue
Host domain{TENANT_ENV}.checkout.api.{DOMAIN_NAME}
Devicedesktop
Basic Authenticationdisabled
Is Genericenabled*

{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:

  1. Go to Shops > Shop > Storefront > Checkout Settings > Checkout Frontend Configuration.
  2. Click Add New Host.
  3. Under General Information, set the Host domain, Device, Theme name, and Theme version.
  4. Set Basic Authentication or Is Generic.
  5. Click Save.

Add a New Host.

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

  1. Go to Shops > Shop > Storefront > Checkout Settings > Checkout Frontend Configuration > General Configuration > Hosts.
  2. Select the tab Whitelisted Hosts. You can whitelist specific origin domains or allow all by adding an asterisk (*).
  3. 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.

  1. Go to Shops > Shop > Storefront > Checkout Settings > Checkout Frontend Configuration> Routes & Domains.
  2. 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

  1. Go to Shops > Shop > Storefront > Checkout Settings > Checkout Frontend Configuration > General Configuration > Routes.
  2. Set the new path for the required area of your shop.
  3. Click Save Changes to save the configuration and fields.
AttributeValue
Include Shop Id On Redirectdisabled
Provide Login State Notificationenabled
Provide Logout State Notificationenabled

Default routes

The following routes are added for desktop, mobile and app by default:

AttributeValue
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

  1. Go to Shops > Shop > Storefront > Checkout Settings > Checkout Frontend Configuration > General Configuration > Domains.
  2. Set the new URL.
  3. 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.