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

Configure Checkout in the SCAYLE Panel

1. 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

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.

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:

You can find an example of the header size properties in JSON format below:

json

Copy

"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.

javascript

Copy

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.

javascript

Copy

  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.

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

json

Copy

{
    "dynamicFields": {
        "register": {
            ...
        }
    }
}

Checkout as Guest

Copy

{
    "dynamicFields": {
        "guest": {
            ...
        }
    }
}

Shipping Addres

Copy

{
    "dynamicFields": {
        "shippingAddress": {
            ...
        }
    }
}

Billing Address

Copy

{
    "dynamicFields": {
        "billingAddress": {
            ...
        }
    }
}

Collection Point

Copy

{
    "dynamicFields": {
        "collectionPoint": {
            ...
        }
    }
}

Payment Options

Copy

{
    "dynamicFields": {
        "paymentOptions": {
            ...
        }
    }
}

Payment Step (After Payment Options)

Copy

{
    "dynamicFields": {
        "payment": {
            ...
        }
    }
}

Payment Step (Below Mobile Basket, Above 'Pay Now' Button

Copy

{
    "dynamicFields": {
        "paymentBelowMobileBasket": {
            ...
        }
    }
}

Birth Date

Copy

{
    "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.

Copy

{
    "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.

json

Copy

{
    "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.

Copy

{
    "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)

json

Copy

{
    "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, ...)

Copy

{
    "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, ...)

json

Copy

{
    "texts": [{ "name": "term_conditions_info", "i18nKeys": { "label": "custom1" } }]
}

Sample configuration

json

Copy

{
    "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.

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

Copy

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

{TENANT_ENV}: Configured tenant environment name
{DOMAIN_NAME}: Configured domain name
*: 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.

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.

Default routes

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

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.