urls - URLs (web addresses) - WEBSALE Dokumentation

The urls node bundles the URL configuration of the shop. It covers language / country alternatives via hreflang, the handling of faulty or outdated URLs, and the build-up and cleanup of SEO URLs in terms of structure, separators and parameter cleanup.

`urls*` - Basic structure

The basic structure of the urls node is shown below:

{
  "urls": {
    "hreflang": {},
    "redirects": {},
    "urls": {}
  }
}

Parameter description

Parameter	Description
`hreflang`	Controls which page URLs search engines should know via `hreflang`.
`redirects`	Controls how the shop reacts to faulty or no longer valid URLs: with status code 404 or 410, or with a redirect.
`urls`	Controls how speaking URLs in the shop are built and cleaned up.

`urls.hreflang` - Language / country alternatives for page URLs

This node controls which alternative page URLs (e.g. DE/AT/CH/EN) search engines should know via hreflang for a page. For this, subshops are combined into groups. For each group you can specify whether products / categories are assigned automatically or manually and in which export format (CSV / JSON) the assignments should be output. You can open this setting directly in the Admin Interface via the following link: https://<shop-domain>/admin/config/urls.hreflang (Deeplink overview)

Example configuration

{
  "collectInfo": true,
  "subshopGroups": [
    {
      "categoryAlloc": "automatic",
      "checkMode": true,
      "fileNameCategory": "catAlloc.csv",
      "fileNameProduct": "prodAlloc.csv",
      "fileType": "csv",
      "groupId": "hrefGroup",
      "groupName": "Href-Group",
      "productAlloc": "automatic",
      "subshops": [
        {
          "default": true,
          "subshopId": "deutsch"
        },
        {
          "default": false,
          "subshopId": "englisch"
        }
      ]
    }
  ]
}

Parameter overview

Parameter	Type	Description
`collectInfo`	bool	If this option is enabled, the system collects information about which language / country versions belong to which page and whether the links are set correctly. This helps to identify issues. Default: `true`
`subshopGroups`	list (object)	List of subshop groups combined for hreflang.
`groupId`	string	Unique identifier of the hreflang group within `subshopGroups`. Freely selectable.
`groupName`	string	Readable name of the hreflang group.
`checkMode`	bool	Activates checks that find typical errors in the language / country assignments.
`productAlloc`	enum	Defines how language / subshop specific counterparts of the same product (hreflang variants) are linked. `automatic` — automatic assignment. `manual` — assignment is maintained manually (e.g. via file / list). Default: `automatic`
`categoryAlloc`	enum	Defines how language / subshop specific categories are linked. `automatic` — automatic assignment. `manual` — assignment is maintained manually (e.g. via file / list). Default: `automatic`
`fileType`	enum	Defines the export format of the hreflang assignments for categories and products. `csv` — provides the export file in CSV format. `json` — provides the export file in JSON format.
`fileNameProduct`	string	Defines the file name for the export of the product assignments.
`fileNameCategory`	string	Defines the file name for the export of the category assignments.
`subshops`	list (object)	Contains a list of available language / subshops.
`subshopId`	string	ID of the subshop, e.g. `de` or `en`.
`default`	bool	Marks the primary language / region. Default: `false`

`urls.redirects` - Behavior for pages not found

The redirects sub-node controls how the shop reacts to no longer valid or faulty URLs, e.g. deleted products or categories or outdated links. It also specifies which error page template is used, whether to automatically redirect to the parent category if possible, and which page serves as the fallback. It also determines which HTTP status code the shop responds with.

Status code instead of redirect

For search engines, it is essential that non-existent pages are reported as such. If the shop redirects to another page instead, search engines continue to treat the old URL as valid. For this reason, the shop responds with status code 404 by default and displays the error page directly under the requested URL. The URL in the address bar remains unchanged. The behavior is defined by the errorPageBehavior parameter:

Value	Status code	Behavior
`notFound`	404 Not Found	The error page is displayed under the requested URL. Suitable for pages that do not exist or no longer exist. Default value.
`gone`	410 Gone	The error page is displayed under the requested URL. The status code tells search engines that the page has been permanently removed.
`redirect`	301 Moved Permanently	The caller is redirected to the URL of the error page. If the home page is the error page, the redirect leads to `/`.

Which page serves as the error page is determined by redirectFallback and errorPageTemplate. With notFound and gone, $wsViews.current.status outputs the sent status code on the error page, i.e. 404 or 410. This allows you, for example, to output a suitable notice text in the template. You can open this setting directly in the Admin Interface via the following link: https://<shop-domain>/admin/config/urls.redirects (Deeplink overview)

Example configuration

{
  "errorPageBehavior": "notFound",
  "errorPageTemplate": "error.htm",
  "redirectFallback": "errorPage",
  "redirectToParentCategory": true
}

Parameter overview

Parameter	Type	Description
`errorPageBehavior`	enum	Defines how the shop responds when a requested page was not found. `notFound` — status code 404, the requested URL stays the same `gone` — status code 410, the requested URL stays the same `redirect` — redirect to the URL of the error page Default: `notFound`
`errorPageTemplate`	string	Name of the template used for error pages (e.g. the 404 page).
`redirectFallback`	enum	Fallback target when no specific redirect applies. `startPage` — on error, redirects to the home page of the shop. `errorPage` — on error, redirects to the default error page. Whether a redirect takes place or the page is displayed under the requested URL is defined by `errorPageBehavior`. Default: `startPage`
`redirectToParentCategory`	bool	If `true`, faulty URLs are redirected to the parent category where possible. Default: `true`

`urls.urls` - General settings for SEO URLs

The urls sub-node controls how speaking URLs in the shop are built and cleaned up. Among other things, this defines whether the URL logic is active, whether URLs are lowercased and which separators are used. You can open this setting directly in the Admin Interface via the following link: https://<shop-domain>/admin/config/urls.urls (Deeplink overview)

Example configuration

{
  "active": true,
  "alwaysEndWithSlash": true,
  "generate": [
    {
      "options": {
        "urlschema": [
          {
            "schema": [
              {
                "fields": [
                  "categoryPath"
                ],
                "listOptions": {
                  "categoryField": "name",
                  "order": "reverse",
                  "top": 2
                },
                "optional": true,
                "separator": "/",
                "type": "field"
              },
              {
                "fields": [
                  "name"
                ],
                "optional": true,
                "separator": "/",
                "type": "field"
              }
            ],
            "subshop": "englisch"
          },
          {
            "schema": [
              {
                "fields": [
                  "categoryPath"
                ],
                "listOptions": {
                  "categoryField": "name",
                  "order": "normal",
                  "top": 1
                },
                "optional": true,
                "separator": "/",
                "type": "field"
              },
              {
                "fields": [
                  "name"
                ],
                "optional": true,
                "separator": "/",
                "type": "field"
              }
            ]
          }
        ]
      },
      "service": "seoUrlHandler.category"
    },
    {
      "options": {
        "urlschema": [
          {
            "schema": [
              {
                "fields": [
                  "brand"
                ],
                "optional": true,
                "separator": "/",
                "type": "field"
              },
              {
                "fields": [
                  "categoryPath"
                ],
                "listOptions": {
                  "categoryField": "name",
                  "order": "normal",
                  "top": 1
                },
                "optional": true,
                "separator": "/",
                "type": "field"
              },
              {
                "fields": [
                  "name"
                ],
                "optional": true,
                "separator": "/",
                "type": "field"
              }
            ]
          }
        ]
      },
      "service": "seoUrlHandler.product"
    }
  ],
  "lowercase": true,
  "mappings": {
    "ß": "ss",
    "ä": "ae",
    "ö": "oe",
    "ü": "ue"
  },
  "parametersToRemove": [
    "ref"
  ],
  "suffixSeparator": "-",
  "wordSeparator": "_"
}

Parameter overview

Parameter	Type	Description
`active`	bool	Turns the URL logic on / off. If `false`, the automatic SEO URL processing (the function that makes the URLs search engine friendly) is disabled. Default: `true`
`lowercase`	bool	If `true`, URLs are output in lowercase (e.g. `/produkte/t-shirt`).
`suffixSeparator`	string	Separator between the base URL and the suffix, e.g. the product ID. Often `-`, e.g. `/t-shirt-1234`.
`wordSeparator`	string	Separator between words in the path, e.g. `_` → `/t_shirt_herren/`.
`alwaysEndWithSlash`	bool	If `true`, generated URLs always end with `/` (e.g. `/herren/t-shirts/`).
`parametersToRemove`	list (string)	List of query parameters to be removed from URLs (e.g. tracking parameters like `ref`, `utm`).
`mappings`	map	Character mappings for URL generation. Key = original character (often used for umlauts), value = replacement character sequence.
`<key>`	string	Original character (e.g. `ä`, `ß`) to be replaced in URLs.
`<value>`	string	Replacement characters (e.g. `ae` instead of `ä`) that replace the original character.
`generate`	list (object)	An entry in `generate` describes URL generation for a specific type, e.g. categories or products.
`service`	string	Name of the URL handler, e.g. `seoUrlHandler.category`.
`options`	object	Options for this service, in particular the definition of URL schemas via `urlschema`.
`urlschema`	list (object)	Each `urlschema` describes a schema for assembling the URL path.
`subshop`	string	Subshop ID for which this schema applies (e.g. `englisch`).
`schema`	list (object)	List of schema components that build the URL path in sequence.
`type`	string	Type of the schema component, e.g. `field`.
`fields`	list (string)	List of field names whose values flow into this section (e.g. `categoryPath`, `brand`, `name`).
`separator`	string	Separator placed after this section in the URL (e.g. `/`).
`optional`	bool	If `true`, the component is skipped if no values are present.
`listOptions`	object	Additional options if the field is a list / hierarchy (e.g. `categoryPath`).
`categoryField`	string	Field used for the category name (typically: `name`).
`order`	enum	Order in which categories are output. `normal` — from top to bottom. `reverse` — from bottom to top.
`top`	int	Number of levels to be taken over (e.g. `1` → only the top category or `2` → the top two levels).

​urls* - Basic structure

​Parameter description

​urls.hreflang - Language / country alternatives for page URLs

​Example configuration

​Parameter overview

​urls.redirects - Behavior for pages not found

​Status code instead of redirect

​Example configuration

​Parameter overview

​urls.urls - General settings for SEO URLs

​Example configuration

​Parameter overview

`urls*` - Basic structure

Parameter description

`urls.hreflang` - Language / country alternatives for page URLs

Example configuration

Parameter overview

`urls.redirects` - Behavior for pages not found

Status code instead of redirect

Example configuration

Parameter overview

`urls.urls` - General settings for SEO URLs

Example configuration

Parameter overview