Hostname Aliases

Merchants create hostname aliases for the following reasons:

• Single domain for multiple sites: a merchant wants a single domain that is used by multiple sites by adding a site-path mapping. For example, site 1, locale A is www.my-shop.com/us, site 2, locale A is www.my-shop.com/uk, and site 2, locale B is www.my-shop.com/de.
• Multiple domains: a merchant has purchased new site names and wants the old domains to remain active, even if the sites have been shut down, so they still get the traffic from the old sites. For example, www.myshop.com, myshop.com, or www.myothershopdomain.com.
• Misspellings: site aliases are used for misspelling of site names. For example, amerzon instead of amazon or www.myshop.com and www.myshops.com.
• Locale-specific pages: Salesforce B2C Commerce can associate an alias with a locale so www.myshop.de triggers the de_DE locale. See the Localized mapping section.
• Landing pages: B2C Commerce can associate an alias with a landing page so that shoes.myshop.com goes to the Shoes category page
• Device-specific pages: B2C Commerce can associate an alias with device-specific pages so that customers on web-ready devices, such as mobile phones, can access the site.
  

  Note With changing technologies, best practice is transitioning to responsive design regarding device-specific pages. Having device-specific pages is no longer preferred.

Production Instance Hostname

The Production instance hostname is similar to your.instance.hostname.example.com, with an IP address such as 100.100.100.1. This hostname is used to access Business Manager and to connect to UX Studio, WebDav, and other development connections. While you can use it to view the storefront, customers must not use it to access the storefront because it isn't best practice for SEO, doesn't promote brand marketing, and isn’t secure.

Accessing the Storefront Homepage with Your Hostname

If you want your own hostname, such as www.mydomain.com, to directly access the storefront homepage and link to an SSL certificate, you must do the following:

• Purchase a domain, and configure your DNS (Domain Name Service) for that domain to define a hostname.
• Obtain an SSL certificate containing that name, or multiple names from a certificate authority to be used on your storefront. Each certificate installed needs a unique IP address. The first certificate installed shares the IP address with the B2C Commerce hostname. For example, if the B2C Commerce hostname is production.realm.web.demandware.net and the IP address is 100.100.100.1, the first certificate installed gets the IP address 100.100.100.1. If a second certificate is installed it gets a new IP address, such as 100.100.100.2. You must also ensure that your DNS is updated with the IP of the corresponding hostnames.
• Add the hostname to your hostname alias file as part of a rule.
• If your host is listed in Business Manager: site | SEO | Aliases, and only one locale is used for the site, you can create links to the home page that are search-friendly, because they don't require additional information to determine the locale.

Terminology

URL syntax in this topic uses the following terms:

Hostname Alias File

The hostname alias file defines what hostnames or domains are supported by B2C Commerce. It also defines what pipelines or controllers are triggered for a specific URL. This file enables a Production instance with multiple IP addresses to provide different storefront content for multiple domains per site or multiple sites per realm. This file is required for a Production instance launch.

For more specific information on mappings, see URL Redirects.

You can create a set of rules that controls how different URLs are processed by B2C Commerce. These rules use the JSON (Java Script Object Notation) format (see Json.Org).

Include the proper https-host in the alias file. The https-host must reflect the host name.

For example, www.mysite.com maps as:

            { "__version": "1", "settings": { "http-host": "www.mysite.com", "https-host": "www.mysite.com" } }
            

See Configuring a Hostname Alias.

You can also configure your hostname alias file to avoid multiple entry points and duplicate URLs, thus increasing the SEO value of your storefront site. See the Mapping Rule Syntax section.

For additional information on how B2C Commerce constructs URLs, see URL Rules URL Syntax.

Note The file format allows colons for property value assignments instead of equal signs. Although equal signs are allowed for backward compatibility, colons are recommended because they are valid JSON and don't cause problems if you choose to validate your file in an external JSON debugger.

File Format

The following code shows the basic file format:

{"__version": "1", 
"settings": { 
     "http-host": "httphostname", 
     "https-host": "httpshostname",
     "job-hostnames":
      {
        "default":"www.my-default-host.com",
        "de":"www.my-de-host.com",
        "en":"www.my-en-host.com"
      }, 
     "site-path": "sitepath", 
     "default" : "defaultValue",
     "site-path-trailing-slash" : "yes" } 
"hostName1": [
   { mappingRule1 },
   { mappingRuleN }
 ],
"hostNameN": [
   { mappingRule1 },
   { mappingRuleN }
]
}
 

The parameters are as follows:

*The settings property works only when there’s one primary domain on a site, to which all other hostnames redirect. If the site supports multiple domains or hostnames, it's best to leave settings undefined and comment this entire section out. You should use this property if you want all of your sites to use the same host.

File Example

{
    "__version": "1",

    "www.mybrand.com" : [{"pipeline": "Home-Show" }],

    "mybrand.com": [{"host": "www.mybrand.com", "path":"/"}]

}

Mapping Rule Overview

"www.mybrand.com" : [{"pipeline": "Home-Show" }],

"mybrand.com": [
{ "host": "www.mybrand.com", "path":"/" }]

{
  "outlet.mybrand.com": [
    {
      "pipeline": "Search-Show",
      "params": { "cgid": "category-subcategory-outlet" }
    }
  ],
  "m.mybrand.com": [
    {
      "pipeline": "mHome-Show"
    }
  ],
  "www.mybrand.com": [
    {
      "if-agent-contains": ["iphone", "ipod", "android"],
      "host": "m.mybrand.com"
    }
  ]
]

When using a filter such as if-agent-contains, the JSON format doesn't allow an ELSE statement inside a code block; it only executes the one line host:, so you need another block for www to handle regular browsers that don’t match mobile.

Warning

If the hostname alias file contains a JSON error, Business Manager notifies you of the error, but saves your changes to the file. At run time, however, the file isn't used if an error exists inside it. You should Debug the File using a separate tool to ensure that it's valid before you save it in Business Manager.

In previous versions, you set the http and https config for aliases in the Settings tab under Manage Sites. This tab is now obsolete. However, it still exists in Business Manager to support legacy implementations. If there is data in the fields in the Manage Sites Settings tab in addition to the JSON format alias file, the URLUtils() method behaves problematically. The Settings tab fields must be blank for a JSON alias file to be used.

Note If you’re migrating from the legacy implementation, changes to the settings don't take effect until an alias file for the corresponding site is saved. After removing data from the Settings tab, you must navigate to SEO, open the alias file, and save it to activate your changes.

Important

It isn’t possible to set up a URL redirect or mappings for the following paths because the keywords dw, _dw, and s are reserved by B2C Commerce.

http://hostname/dw
http://hostname/_dw
http://hostname/s

Mapping Rule Syntax

Each mapping rule is defined by a set of attributes and looks like the following:

{
   "www.my-host.com":[{"pipeline":"Home-Show", "apply-to-host-only-request-with-params":"true"}] 
   "name": "mobile",
   "if-agent-contains": ["iphone","ipod"],
   "if-site-path": "DE",
   "host": "m.shop.com",
   "path": "index.html"
   "pipeline": "Summer-Start",
   "locale": "de",
   "params": {...},   
}

The parameters are as follows:

Parameter	Description
apply-to-host-only-request-with-params	Optional. Using this parameter, you can control B2C Commerce behavior using the configuration in your aliases file, shown as follows, and perform hostname redirects for these requests directly: "apply-to-host-only-request-with-params": "true" When perform hostname redirects for these requests directly, B2C Commerce retains the request parameter and inserts the configured parameter in the hostname destination URL. When the request parameter and the configured parameter identifier are equal, the request parameter is preferred. See the examples below. See Creating Home Page Links. See Dynamic Mappings.
description	Optional. Describe the parameter. For example, using site-path-trailing-slash: A trailing slash is added (or not) to the redirected site path.
entry-point-destination	Optional. Use with entry-point-pipelines to automatically redirect requests to avoid duplicate home page URLs.
entry-point-pipelines	Optional. Use with entry-point-destination to automatically redirect requests to avoid duplicate home page URLs. Entry point pipelines can point to controllers and pipelines.
host	Optional. The name of the host to which the request is redirected. Note When configuring a hostname redirect, you typically use a rule like this: {"host":"my.host.com", "path":"uk"} or {"host":"my.host.com", "pipeline":"Home-Show"}. When you have a path and pipeline, the redirect is unclear because requests with old-hostname + path are redirected to this new-hostname + path, which is used for host-only requests. So, when you have these two parameters, the pipeline is preferred.
if-agent-contains	Optional. An IF condition to indicate that the following rule is only executed if the attribute condition is met. The attribute condition is an optional list of strings. If the attribute isn't provided, the rule is always selected. This is intended to allow redirects to different URLs for different devices.
if-site-path	Optional. When this property is set, B2C Commerce checks its value against the site path in the entered URL, looking for a match. If it finds a match, B2C Commerce uses the mapping rule. However, in this case, B2C Commerce recognizes only the name, locale, pipeline, and params properties. It ignores the host, path, and if-agent-contains properties. This property is also checked when B2C Commerce generates storefront URLs. For URL generation, B2C Commerce uses the first mapping rule that matches the current hostname and locale. If the matching mapping rule specifies a value for the if-site-path property, the site path is added to the generated URL. Note The if-site-path and site-path parameters are only valid in the corresponding section, where site-path is a setting and if-site-path is a hostname rule. B2C Commerce generates and consumes URLs based on the configured if-site-path or site-path. When using if-site-path statement in a hostname rule, site-path and http(s)-host in the settings sections must be empty or defined for a different hostname.”
locale	Optional. The locale to use when mapping to a pipeline or to a site path.
Name	Optional. The name for the rule.
params	Optional. Parameters to add to the pipeline.
path	Optional. The path that the customer is redirected to via a permanent 301 redirect. To redirect the customer, B2C Commerce constructs a URL by appending the value of the path property to the value of the host property. However, if the host property isn't configured, B2C Commerce ignores the path property. Also, B2C Commerce adds the value of the path property to the value of the host property only if the entered URL is a hostname-only request; otherwise, B2C Commerce adds the path extracted from the request URL to the value of the host property.
pipeline	Optional. A pipeline triggered by the hostName which is used if no host is provided. Pipeline rules are only used if no host is supplied. You can use the locale and params syntax to specify a locale and parameters for the file.
site-path-trailing-slash	Optional. A trailing slash is added (or not) to the redirected site path. See the example below.

Example 1: Controlling the Site Path Trailing Slash

You can control the site path trailing slash for each site path with the site-path-trailing-slash setting.

Start by configuring the preferred HTTP/HTTPS site hostname, as follows:

"settings" : { "http-host" : "www.your-http-hostname.com", "https-host" : "www.your-https-hostname.com",
 "site-path": "en",
 "site-path-trailing-slash" : "yes" } 

Then define the hostname rules, as follows:

"www.your-hostname.com" : [
 { "locale" : "default" },
 { "if-site-path": "en", "site-path-trailing-slash" : "yes", "locale" : "en" },
 { "if-site-path": "de", "site-path-trailing-slash" : "no", "locale" : "de" } ] 

Requests are automatically redirected as shown here:

Note If you don't define this configuration, URLs are generated without a site path and no redirect is made.

Example 2: using the apply-to-host-only-request-with-params setting

This attribute enables you to forward hostname requests with parameters to the configured pipeline, for example:

"www.my-host.com":[{"pipeline":"Home-Show",
            "apply-to-host-only-request-with-params":"true"}] 

This example forwards the requests www.my-host.com/ and www.my-host.com/?param=aValue to the Home-Show pipeline and preserves the original URL parameters.

Performing hostname redirects Directly

Using this parameter, you can perform hostname redirects for these requests directly. B2C Commerce retains the request parameter and inserts the configured parameter in the hostname destination URL. When the request parameter and the configured parameter identifier are equal, the request parameter is preferred.

This is the configuration in the alias file:

"www.your-hostname.com" :
               [ { "host": "www.your-other-hostname.com", "path": "/", "params" : {"cfgParam":"aOtherValue"}} },
               { "apply-to-host-only-request-with-params": "true" }]

With this configuration, the following request:

www.your-hostname.com/?reqParam=aValue

Is redirected to the following:

www.your-other-hostname.com/?reqParam=aValue&cfgParam=aOtherValue

Example 3: integrate default HTTP and HTTPS host Names

The following example configures the main HTTP and HTTPS hostnames for the production instance. The settings section is optional.

"settings": {
            "http-host": "www.sitegenesis.com",
            "https-host": "secure.sitegenesis.com"
            }
            ],

Example 4: Redirect from Alternate URL to Preferred Domain

The following example is a rule that redirects the alternate URL sitegenesis.com to the preferred domain. If a customer enters sitegenesis.com as their URL (http://sitegenesis.com/*), where * is any path, they are redirected via a 301 redirect to http://www.sitegenesis.com/*.

"sitegenesis.com": [
            {
            "host": "www.sitegenesis.com",
            }
            ],

Example 5: Redirect from Misspelled URL to Preferred Domain

This example shows redirect from the misspelled URL sitegensis.com to www.sitegenesis.com. If a customer enters sitegensis.com as their URL (http://sitegensis.com/*) they are redirected via a 301 redirect to www.sitegenesis.com.

"sitegensis.com": [
            {
            "host": "www.sitegenesis.com",
            }
            ],

Example 6: Use Preferred Locale with Localized Host Name

This example shows how to associate locale with a localized URL www.sitegenesis.de.

"www.sitegenesis.de": [
            {
            "locale": "de_DE",
            }
            ],

Example 7: Redirect from Landing Page Link to Category

This example shows a hostname-only URL http://electronics.sitegenesis.com/ that results in a call to the Search-Show pipeline with a category ID parameter of electronics. This can be used in marketing emails to direct a customer to a specific category or page.

"electronics.sitegenesis.com": [
            {
            "pipeline": "Search-Show",
            "params" : {"cgid"="electronics"}
            }
            ],

Example 8: redirect based on client device

Host redirect is based on the user agent header. With each rule, it's possible to associate precondition based on content of "user-agent" http header. In the example below an HTTP requests with "User-Agent" header containing "iPhone" or "iPod" will be redirected (301) to apple.sitegenesis.com and those with "blackberry" to bb.sitegenesis.com.

"www.sitegenesis.com": [
            {
            "if-agent-contains": ["iphone","ipod"],
            "host": "apple.sitegenesis.com",
            },
            {
            "if-agent-contains": ["blackberry"],
            "host": "bb.sitegenesis.com",
            }
            ],

Example 9: Three Sites Sharing Single Host Name

In this example, three existing sites previously used different host names. Because each of these sites supports a single locale, you don't have to specify the locale in your mapping rules. Your goal is to have all three sites share the host name (www.my-site.com) but use different site paths to differentiate themselves:

• Site 1 in the past used www.my-site.uk and you want to change it to www.my-site.com/UK.
• Site 2 in the past used www.my-site.com and you want to change it to www.my-site.com/US.
• Site 3 in the past used www.my-site.de and you want to change it to www.my-site.com/DE.

You also want B2C Commerce to redirect URLs containing old hostnames to the new hostname plus site path values.

To accomplish these goals, you configure the hostname alias file for site 1 as follows:

"settings" : 
            {
            "http-host" : "www.my-site.com",
            "https-host" : "www.my-site.com", 
            "site-path" : "UK", 
            "default" : "false"
            }
            
            "www.my-site.uk": 
            [       
            {
            "host" : "www.my-site.com", "path" : "UK"            
            }
            ] 
         

Next, you configure the hostname alias file for site 2 as follows:

"settings" : 
            {
            "http-host" : "www.my-site.com",
            "https-host" : "www.my-site.com", 
            "site-path" : "US", 
            "default" : "true"
            }
         

Finally, you configure the hostname alias file for site 3 as follows:

"settings" : 
            {
            "http-host" : "www.my-site.com",
            "https-host" : "www.my-site.com", 
            "site-path" : "DE", 
            "default" : "false"
            }
            
            "www.my-site.de": 
            [       
            {
            "host" : "www.my-site.com", "path" : "DE"            
            }
            ] 
         

Example 10: a Single Site Supporting Multiple Host Names and Locales

When you want to redirect from domain A to domain B with the same site-path mapping for both domains, you must configure if-site-path conditions for both domains.

In this example, you have a single site that supported multiple host names in the past, each of which supported a single locale. As in the previous example, you want B2C Commerce to redirect the old hostnames to the new hostname plus site path values:

• The existing host name www.my-site.uk (whose locale is en_UK) should now redirect to www.my-site.com/UK.
• The existing host name www.my-site.com (whose locale is en_US, the default locale) should now redirect to www.my-site.com/US.
• The existing host name www.my-site.de (whose locale is de_DE) should now redirect to www.my-site.com/DE.

To accomplish these goals, you configure the hostname alias file for the site as follows:

"settings" : 
            {
            "http-host" : ",
            "https-host" : ", 
            "site-path" : ", 
            "default" : "
            },
            
            "www.my-site.com": 
            [       
            {
            "locale" : "en_US",
            },
            {
            "locale" : "de_DE",
            "if-site-path" : "DE"
            },
            {
            "locale" : "en_US",
            "if-site-path" : "US"
            },
            {
            "locale" : "en_UK",
            "if-site-path" : "UK"
            },
            ], 
            
            "www.my-site.de": 
            [       
            {
            "host" : "www.my-site.com", "path" : "DE"            
            }
            ], 
            
            "www.my-site.uk": 
            [       
            {
            "host" : "www.my-site.com", "path" : "UK"            
            }
            ]

Example 11: Two Sites with Multiple Hosts and Locales

In this example, you want two sites (site 1 and site 2) to work with the multiple host names and locales. Both sites acknowledge the host names www.my-site.eu and www.my-site.com.

For the first host name (www.my-site.eu), you want to specify the following:

• The host name www.my-site.eu should work by itself without a site path. B2C Commerce should direct the URL to site 1, and the default locale should be en.
• The URL segment www.my-site.eu/DE should direct the URL to site 1, and the locale should be de.
• The URL segment www.my-site.eu/FR should direct the URL to site 1, and the locale should be fr.
• The URL segment www.my-site.eu/US should direct the URL to site 2, and the locale should be en.

For the second host name (www.my-site.com), you want to specify the following:

• The host name www.my-site.com should work by itself without a site path. B2C Commerce should direct the URL to site 2, and the default locale should be en.
• The URL segment www.my-site.com/FR should direct the URL to site 2, and the locale should be fr.
• The URL segment www.my-site.com/UK should direct the URL to site 1, and the locale should be en.
• The URL segment www.my-site.com/DE should direct the URL to site 1, and the locale should be de.