Redirects

Overview

The redirects middleware, included in the SCAYLE Storefront SDKs provides support for SCAYLE Redirects within your SCAYLE Storefront application. This guide explains what redirects are, the importance of redirects for your e-commerce business as well as the technical aspects of the redirects middleware and provides information on how this module can be configured.

The Importance of Redirects

In the dynamic environment of an e-commerce application, URLs often change. Products get updated, categories restructured, or marketing campaigns launched. Using redirects effectively is vital for several key reasons:

1. Preserving SEO Value: When you change a URL for a product or category page that has earned search engine rankings, a redirect (specifically a 301) tells search engines like Google that the page has moved permanently. This helps transfer the accumulated SEO value from the old URL to the new one, minimizing the impact on your organic search traffic. Without redirects, you risk losing valuable rankings.
2. Ensuring a Smooth User Experience: Clicking a link (from search results, a bookmark, or another site) only to land on a "404 Not Found" error page is frustrating for users and can lead to lost sales. Redirects provide a seamless transition, automatically taking visitors to the correct, live page even if the URL they used is no longer active. This maintains customer satisfaction and keeps them on their purchase journey.
3. Tracking Marketing Campaigns: Redirects are useful for marketing purposes. You can create short, memorable vanity URLs for specific campaigns (e.g., yourbrand.com/summersale) that redirect to a longer, perhaps parameter-filled, landing page URL. This makes URLs easier to share and can help track the effectiveness of different campaigns by associating specific redirects with specific traffic sources.

Types of Redirects

Redirects can be created on both global and country shop levels. You can set redirects using either an absolute URL or a relative URL.

• Absolute URLs are best used when you want to redirect from a single, specific URL. For example, if you are no longer selling a certain brand of sweater in your shop, you would want to redirect from the entire URL of that specific listing.
• Relative URLs are best used when you want to redirect from part of a domain. For example, if you have a category called "Men's Jumpers" in your shop, and you want to rename the category to "Men's Sweaters", you would want to set up a redirect for /men/jumpers to /men/sweaters. This way, every product in the "Men's Jumpers" shop category would be included in the redirect, without needing to create an individual redirect for each listing.

Redirect Status Codes

How to choose between temporary and permanent redirects?

A permanent redirect (301, 308) signals to browsers and search engines that a page has moved permanently to a new location. It's the most common type of redirect for SEO purposes, as it strongly suggests transferring all ranking signals to the new URL.

Common use cases for permanent redirects:

• Permanently changing a product or category page URL (e.g., after renaming or restructuring).
• Migrating your entire store to a new domain name.
• Consolidating duplicate content by redirecting variations to a single canonical URL.

A temporary redirect (302, 307) indicates that a page has moved temporarily to a different location. Search engines are generally advised not to pass significant link equity, as the original URL is expected to be used again in the future.

Common use cases for temporary redirects:

• Directing users to a specific promotional page only during a limited-time sale or event.
• Temporarily taking a page offline for maintenance and sending users to an informational page or the homepage.
• A/B testing different versions of a page for conversion optimization.

Redirect Inheritance Rules

The following are some considerations for how redirects operate at the global and shop-country levels:

• Redirects created on the global shop level are inherited to all country-level shops.
• Inherited redirects can be edited on the country level. Edited country redirect values will overwrite the global values.
• Redirects can be created on the country level separately. Redirects created at the country level can't be overwritten and are only valid for the respective shop-country.

Managing Redirects

Redirects can be managed through the SCAYLE Panel as well as the Admin API.

Technical Implementation

When the redirects module is enabled, it will intercept requests and look up possible redirects through the Storefront API. If a matching redirect is found, it will send a redirect response instead of rendering the regular route. In the response, it will set the Location header to the target property of the redirect and the statusCode property (302, 303, 307, or 308) will be used as the status of the response.

Path Normalization

Before querying for possible redirects, the request URL is transformed into a normalized URL by removing trailing slashes. For example, https://example.com/products/ is turned into https://example.com/products.

Absolute and Relative URLs

For every request, both the absolute and relative URLs are considered for redirects. If there are matching redirects for both the absolute and relative URLs, the redirect for the relative URL will be used.

Caching

To reduce latency and load on the Storefront API, the responses to redirect queries are cached. The cache TTL is 120 seconds, so the results should be visible within a few minutes after making a change to the redirect configuration.

Configuration

The behavior of redirects can be configured through the module configuration in nuxt.config.ts . These same configuration options can also be set through environment variables.

typescript

Copy

Redirect Strategy

The redirects.strategy option controls how the redirects logic is executed. It can be set to on-missing or pre-request.

pre-request is the default and the only strategy available before @scayle/[email protected]. When this strategy is enabled, the redirects check will be executed before each request. If a match is found, the redirect will be sent instead of attempting to render the page.

When on-missing is used, the redirects logic will only be executed when the attempt to render results in a 404 response. Before sending the 404 response to the client, the redirects module will first check for applicable redirects and if one is found it will send the redirect instead of the 404. Keep in mind that because this mode only executes on 404 responses, this strategy is not totally compatible with existing redirects. You should ensure that there are no matching routes for any of your redirects before enabling this strategy.

Query Parameter Whitelist

As part of the the path normalization, all query parameters in the original URL that are not in the whitelist will be stripped before looking up the redirect. The stripped query parameters (but not the whitelisted ones) will be re-attached to the redirect URL if one is found.

For example, if a redirect is defined for /men/jumpers to /men/sweaters, it will work even when additional tracking parameters are present.

If a query parameter should be included in the redirect lookup, add it to the whitelist. In this case, it will not be re-appended to the resulting redirect.

References

• Manage Redirects in the SCAYLE Panel (Create absolute or relative redirects, delete or export redirects)
• Use Storefront API to List Redirects or Match a Redirect
• URL Redirects in the Developer Guide