urls - URLs (web addresses) - WEBSALE Dokumentation

The urls node bundles the URL configuration of the shop. It covers language / country alternatives via hreflang, redirects as well as faulty or outdated URLs and the build-up and cleanup of SEO URLs (structure, separators, 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.
`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.

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`, `en`).
`default`	bool	Marks the primary language / region. Default: `false`

`urls.redirects` - Redirects for faulty URLs

The redirects sub-node controls how the shop reacts to no longer valid or faulty URLs (e.g. deleted products / categories or outdated links). It specifies which error page template should be used, whether to automatically redirect to the parent category if possible, and which page to use in general as a fallback.

Example configuration

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

Parameter overview

Parameter	Type	Description
`errorPageTemplate`	string	Name of the template used for error pages (e.g. 404 page).
`redirectFallback`	string	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. Default: `startPage`
`redirectToParentCategory`	bool	If `true`, faulty redirects are sent 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.

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. 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 - Redirects for faulty URLs

​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` - Redirects for faulty URLs

Example configuration

Parameter overview

`urls.urls` - General settings for SEO URLs

Example configuration

Parameter overview