Advanced URL Configurations url
AEM CIF Core Components provides advanced configurations to customize the URLs for product and category pages. Many implementations customize these URLs for search engine optimization (SEO) purposes. The following video details how to configure the UrlProvider
Service and features of Sling Mapping to customize the URLs for product and category pages.
Configuration configuration
To configure the UrlProvider
service according to the SEO requirements and needs, a project must provide an OSGI configuration for the CIF URL Provider configuration.
Product Page URL Format product
Configures the URLs of the product pages and supports the following options:
{{page}}.html/{{sku}}.html#{{variant_sku}}
(default){{page}}.html/{{sku}}/{{url_key}}.html#{{variant_sku}}
{{page}}.html/{{sku}}/{{category}}/{{url_key}}.html#{{variant_sku}}
{{page}}.html/{{sku}}/{{url_path}}.html#{{variant_sku}}
{{page}}.html/{{url_key}}.html#{{variant_sku}}
{{page}}.html/{{category}}/{{url_key}}.html#{{variant_sku}}
{{page}}.html/{{url_path}}.html#{{variant_sku}}
If there is the Venia Reference store:
{{page}}
is replaced by/content/venia/us/en/products/product-page
{{sku}}
is replaced by the product’s SKU, for example,VP09
{{url_key}}
is replaced by the product’surl_key
property, for example,lenora-crochet-shorts
{{url_path}}
is replaced by the product’surl_path
, for example,venia-bottoms/venia-pants/lenora-crochet-shorts
{{variant_sku}}
is replaced by the currently selected variant, for example,VP09-KH-S
Since the url_path
got deprecated, the pre-defined product URL formats use a product’s url_rewrites
and pick the one with the most path segments as alternative if the url_path
is not available.
With the above example data, a product variant URL formatted using the default URL format looks like /content/venia/us/en/products/product-page.html/VP09.html#VP09-KH-S
.
Category Page URL Format product-list
Configures the URLs of the category or product list pages and supports the following options:
{{page}}.html/{{url_path}}.html
(default){{page}}.html/{{url_key}}.html
If there is the Venia Reference store:
{{page}}
is replaced by/content/venia/us/en/products/category-page
{{url_key}}
is replaced by the category’surl_key
property{{url_path}}
is replaced by the category’surl_path
With the above example data, a category page URL formatted using the default URL format looks like /content/venia/us/en/products/category-page.html/venia-bottoms/venia-pants.html
.
url_path
is a concatenation of the url_keys
of a product or category’s ancestors and the product or category’s url_key
separated by /
slash. Each url_key
is considered unique within a given store.Store-specific Configuration store-specific-urlformats
The system-wide category and product page URL formats set by the CIF URL Provider configuration can be changed for each store.
In the CIF Configuration, an editor can select an alternative product or category page URL format. If nothing is selected there, the implementation falls back to the system-wide configuration.
Changing the URL format of a live website may have a negative impact on the organic traffic of your site. See Best Practices below and carefully plan the change of the URL format in advance.
Category-Aware Product Page URLs context-aware-pdps
Since it is possible to encode category information in a product URL, products that are in multiple categories may be addressed with multiple product URLs as well.
The default URL formats select one of the possible alternatives using the following scheme:
- if the
url_path
is defined by the e-commerce backend use it (deprecated) - from the
url_rewrites
use those URLs that end with the product’surl_key
as alternatives - form these alternatives use the one with the most path segments
- if there are multiple, take the first one in the order given by the e-commerce backend
This scheme selects the url_path
with the most ancestors, based on the assumption that a child category is more specific than its parent category. The selected url_path
is considered canonical and is always used as the canonical link on product pages or in the product sitemap.
However, when a shopper navigates from a category page to a product page, or from one product page to another related product page in the same category, it is worthwhile to retain the current category context. In this case, the url_path
selection should prefer alternatives that are within the current category context over the canonical selection described above.
This feature must be enabled in the CIF URL Provider configuration. If enabled the selection scores alternatives higher, when
- they match parts of a given category’s
url_path
from the beginning (fuzzy prefix matching) - or they match a given category’s
url_key
anywhere (exact partial matching)
For example, consider the response for a products query below. Given the following:
- the user is on the “New Products / New in Summer 2022” category page
- the store uses the default category page URL format
The alternative “new-products/new-in-summer-2022/gold-cirque-earrings.html” matches two of the context’s path segments from the beginning. That is, “new-products” and “new-in-summer-2022”. If the store uses a category page URL format that only contains the category url_key
, the same alternative would still be selected as it matches the context’s url_key
anywhere. In both cases, the product page URL is created for the “new-products/new-in-summer-2022/gold-cirque-earrings.html” url_path
.
{
"data": {
"products": {
"items": [
{
"sku": "VA18-GO-NA",
"url_key": "gold-cirque-earrings",
"url_rewrites": [
{
"url": "gold-cirque-earrings.html"
},
{
"url": "venia-accessories/gold-cirque-earrings.html"
},
{
"url": "venia-accessories/venia-jewelry/gold-cirque-earrings.html"
},
{
"url": "new-products/gold-cirque-earrings.html"
},
{
"url": "new-products/new-in-summer-2022/gold-cirque-earrings.html"
}
]
}
]
}
}
}
Specific Category and Product Pages specific-pages
It is possible to create multi-category and product pages for only a specific subset of categories or products of a catalog.
Selection Criteria specific-pages-selection
The selection of a specific category page is straight forward, based on the category’s url_path
or url_key
. Matching subcategories is supported only for URL formats that contain the full category url_path
. Otherwise only an exact matching of the url_key
is possible.
Specific product pages are selected either by the product’s SKU or category. The latter requires some category information to be encoded in the product URL. This functionality is only available for some of the default URL formats. See the following table for a comparison which URL format supports specific page selection by SKU or category.
{{page}}.html/{{url_key}}.html
{{page}}.html/{{category}}/{{url_key}}.html
{{page}}.html/{{url_path}}.html
{{page}}.html/{{sku}}.html
{{page}}.html/{{sku}}/{{url_key}}.html
{{page}}.html/{{sku}}/{{category}}/{{url_key}}.html
{{page}}.html/{{sku}}/{{url_path}}.html
Deep Linking specific-pages-deep-linking
The UrlProvider
is pre-configured to generate deep links to specific category and product pages on author tier instances. This ability is useful to editors, that browse a site using Preview mode, navigate to a specific product or category page and switch back to Edit mode to edit the page.
On publish tier instances on the other hand, catalog page URLs should be kept stable to not lose gains on search engine rankings for example. Because of that publish tier, instances do not render deep links to specific catalog pages per default. To change this behavior, the CIF URL Provider Specific Page Strategy can be configured to always generate specific page URLs.
Multiple Catalog Pages multiple-product-pages
When editors want to have full control of the top-level navigation of a site, using a single catalog page to render the top-level categories of a catalog may not be desired. Instead editors can create multiple catalog pages, one for each category of the catalog they want to include in the top-level navigation.
For that use case, each of the catalog pages may have a reference to a product and category page specific to the category configured for the catalog page. The UrlProvider
uses these connections to create links for the pages and categories in the configured category. However, for performance reasons only the direct catalog page children of a Site’s navigation root / landing page are considered.
It is recommended that the product and category pages of a catalog page are descendant to that catalog page, otherwise components like the Navigation or Breadcrumb may not work correctly.
Customizations customization
Custom URL Formats custom-url-format
To provide a custom URL format, a project can implement either the ProductUrlFormat
or the CategoryUrlFormat
service interface and register the implementation as OSGI service. Those implementations, if available, replace the configured, pre-defined format. If there are multiple implementations registered, the one with the higher service ranking replaces the ones with the lower service ranking.
The custom URL format implementations must implement a pair of methods to build a URL from given parameters, and to parse a URL to return the same parameters respectively.
Combine with Sling Mappings sling-mapping
In addition to the UrlProvider
, it is also possible to configure Sling Mappings to rewrite and process URLs. The AEM Archetype project also provides an example configuration to configure some Sling Mappings for port 4503 (publish) and 80 (Dispatcher).
Combine with AEM Dispatcher dispatcher
URL rewrites can also be achieved by using AEM Dispatcher HTTP server with mod_rewrite
module. The AEM Project Archetype provides a reference AEM Dispatcher config which already includes basic rewrite rules for the generated size.
Best Practices best-practices
Choose the best URL Format choose-url-format
As mentioned before selecting one of the available default formats, or even implementing a custom format, highly depends on the needs and requirements of a store. The following suggestions may help to make an educated decision.
Use a product page URL format that contains the SKU.
The CIF Core Components use the SKU as primary identifier in all components. If the product page URL format does not contain the SKU, a GraphQL query is necessary to resolve it. This resolution may impact the time-to-first-byte. Also, it may be desired, that shoppers can find products by SKU using search engines.
Use a product page URL format that contains the category context.
Some features of the CIF URL Provider are only available when using product URL formats, that encode the category context, like the category url_key
or the category url_path
. Even if those features may not be required for a new store, using one of these URL formats in the beginning helps to reduce migration efforts in the future.
Balance between URL length and encoded information.
Depending on the catalog size, in particular the size and depth of the category tree, it may not be reasonable to encode the full url_path
of categories into the URL. In that case, the URL length could be reduced by including only the category’s url_key
instead. This method supports most of the features that are available when using the category url_path
.
Also, use Sling Mappings to combine the SKU with the product url_key
. In most e-commerce systems, the SKU follows a particular format and separating the SKU from the url_key
for incoming requests should easily be possible. With that in mind, it should be possible to rewrite a product page URL to /p/{{category}}/{{sku}}-{{url_key}}.html
, and a category URL to /c/{{url_key}}.html
respectively. The /p
and /c
prefix are still necessary to distinguish product and category pages from other content pages.
Migrating to a new URL Format migrate-url-formats
Many of the default URL formats are somehow compatible with each other, meaning that URLs formatted by one may be parsed by another one. That helps migrating between URL formats.
On the other hand, search engines need time to recrawl all catalog pages with the new URL format. To support this process and also to improve the end-user experience, it is recommended to provide redirects that forward the user from the old URLs to the new ones.
One approach for that could be, to connect a stage environment to the production e-commerce backend and configure it to use the new URL format. Afterwards obtain the product sitemap generated by CIF products sitemap generator for both the stage and the production environment, and use them to create an Apache httpd rewrite map. This rewrite map can then be deployed to the Dispatcher together with the rollout of the new URL format.
Example example
The Venia Reference store project includes sample configurations to demonstrate the usage of custom URLs for product and category pages. This configuration allows each project to set up individual URL patterns for product and category pages according to their SEO needs. A combination of CIF UrlProvider
and Sling Mappings as described above is used.
hostname.adobeaemcloud.com
folder in ui.content/src/main/content/jcr_root/etc/map.publish/https
according to the used domain name and enable this config by adding resource.resolver.map.location="/etc/map.publish"
to the JcrResourceResolver
config of the project.