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 below.
• 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 is not secure.

Accessing the Storefront Homepage with Your Hostname

Terminology

URL syntax in this topic uses the following terms:

Hostname Alias File

The hostname alias file defines what hostnames/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).

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 below.

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

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:

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 do not match mobile.

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:

"apply-to-host-only-request-with-params": "true"

Examples

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:

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:

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:

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:

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

In addition the above goals, you want to add the EXAMPLE site path to both the www.my-site.eu and the www.my-site.com host names. For this site path, the locale should be en, and the configuration should direct the URL to the Example-DoSomething pipeline, which will take the following parameters:

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

"settings" : 
{
     "http-host" : "",
     "https-host" : "", 
     "site-path" : "", 
     "default" : ""
},

"www.my-site.eu": 
[       
        {
            "locale" : "en",
        },
        {
            "locale" : "de",
                   "if-site-path" : "DE"
        },
        {
            "locale" : "fr",
                   "if-site-path" : "FR"
        },
        {
            "locale" : "en",
                   "if-site-path" : "EXAMPLE",
                   "pipeline" : "Example-DoSomething",
                   "params" : {"cgid":"exampleCategory", "color":"blue" }
        }
], 

"www.my-site.com": 
[       
        {
            "locale" : "de",
                   "if-site-path" : "DE"
        },
        {
            "locale" : "en",
                   "if-site-path" : "UK"
        }
]

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

"settings" : 
{
     "http-host" : "",
     "https-host" : "", 
     "site-path" : "", 
     "default" : ""
},

"www.my-site.eu": 
[       
        {
            "locale" : "en",
                   "if-site-path" : "US"
        }
], 

"www.my-site.com": 
[       
        {
            "locale" : "en",
        },
        {
            "locale" : "fr",
                   "if-site-path" : "FR"
        },
        {
            "locale" : "en",
                   "if-site-path" : "EXAMPLE",
                   "pipeline" : "Example-DoSomething",
                   "params" : {"cgid":"exampleCategory", "color":"blue" }
        }
]

The following table shows how these configurations cause B2C Commerce to handle different entered URLs:

Example 12: Preferred Hostnames for URL Generation Without Request Context

To avoid custom code, the alias file now supports a mapping to define hostnames within the job context. The mapping can be locale-specific, and follow a language fallback from country to language to default locale.

"settings" :
{
    "job-hostnames" :
    {
        "default":"www.my-default-host.com",
        "de":"www.my-de-host.com",
        "en":"www.my-en-host.com"
    }
},
 
"www.my-default-host.com":[{}],
"www.my-de-host.com":[{}],
"www.my-en-host.com":[{}],

The returned hostname for locales (following the language fallback) are as follow:

Debugging the Hostname File as JSON

To make debugging easier, you should choose to use an external JSON debugger, such as the one available at http://www.jsonlint.com/. There are many other tools like this available to test the file.

Don't try to debug the hostname alias file in Business Manager through trial and error. If the file contains any JSON errors, the file is ignored and therefore any configured hostnames fail on the instance. Make sure that the file is valid JSON before saving it in Business Manager.

Testing the Hostname Configuration

Alias configurations can be complex on a Production instance and should be tested before they are added - and not just for syntax. If you don't want to configure and register the DNS and domain names for your test environment, you can configure domain names on your local machine. This is also an option if no domain names are available for your test environment. To test your configuration:

• Determine the IP address of your test system. Enter nslookup your.instance.hostname.example.com into a console.
• Add a hostname mapping to your locale machine's hosts file, typically located in /etc/hosts: 123.45.678.91 my-test-hostname.com.
• Use this or all hostnames that are (locally) pointing to the instance to verify and test your hosts configuration.

Hostname Alias Processing

B2C Commerce performs two different types of host name alias processing: handling entered URLs, and generating storefront URLs. To handle an entered URL, B2C Commerce examines the entered URL, and dispatches the request to the appropriate site for further processing. During storefront URL generation, B2C Commerce constructs URLs that are visible to customers.

Handling entered URLs

When B2C Commerce receives an entered URL from the customer, B2C Commerce checks all hostname alias files for all sites in your organization, looking for a suitable mapping.

1. Is there a match for both the hostName and sitePath inside a settings property?
   • Yes - use the corresponding site (the site whose host name alias file contains the matching settings property) to handle the URL, and then continue to step 5.
   • No - continue to step 2.
2. Outside of any settings property, is there a match for both the hostName and the sitePath (specified in the if-site-path property)?
   • Yes - use the corresponding site to handle the URL, and then continue to step 5.
   • No - continue to step 3.
3. Inside the settings property, is there a match for hostName?
   • Yes - check to see if the defaultValue is true, and if it is, use the corresponding site to handle the URL, and continue to step 5. If no site with a match for hostName sets the defaultValue to true, use the first site in the sites list to handle the URL, and continue to step 5.
   • No - continue to step 4.
4. Outside of any settings property, is there a match for just the hostName?
   • Yes - continue to step 6.
   • No - send an error message to the customer indicating that the requested resource could not be found. Skip all of the remaining steps in this process.
5. Was the matching hostName and sitePath (if any) found in the settings property?
   • Yes - examine the remaining portion of the entered URL (the portion after the hostName and sitePath, if any) to determine the correct locale and nature of the requested resource (that is, to determine whether the URL specifies a category, content asset, or pipeline). If the entered URL specifies only the hostName and sitePath, or only the hostName, execute the Default-Start pipeline and return the response to the customer. Otherwise, retrieve the requested resource (executing a pipeline if necessary) and return the requested resource to the customer. If no locale is specified, use the default locale for the site when retrieving the requested resource. Skip all of the remaining steps in this process.
   • No - continue to step 6.
6. Does the mapping rule contain an if-site-path property?
   • Yes - examine the remaining portion of the entered URL (the portion after the hostName and sitePath) to determine the nature of the requested resource (that is, is the URL specifying a category, content asset, or pipeline). If the remaining portion of the entered URL specifies the name of a category, content asset, or pipeline, retrieve the requested resource (executing the pipeline if necessary). Otherwise, examine the mapping rule to determine the values of the optional name, locale, pipeline, and params properties. Ignore all other property values (for example, ignore the if-agent-contains property). Use the name, locale, pipeline, and params property values to determine how to handle the request. If the entered URL specifies only the hostName and sitePath, check to see if the pipeline and params properties are set; if so, execute the configured pipeline using the configured params (if any); if the pipeline and param properties are not set, execute the Default-Start pipeline, and return the response to the customer. If no locale is specified, use the default locale for the site when retrieving the requested resource. Skip all of the remaining steps in this process.
   • No - continue to step 7.
7. Is the first mapping rule an if-agent-contains rule?
   • Yes - continue to step 8.
   • No - process the first mapping rule. Because B2C Commerce only processes the first successful alias it finds, if-agent-contains must be included as the first mapping in a rule or it's never reached.
8. Is the if-agent-contains condition true?
   • Yes - then process the mapping rule containing the if-agent-contains rule.
   • No - process the rule or condition after the rule associated with the previous if-agent-contains rule.
9. Does the entered URL only contain the hostName?

   • Yes - the entered URL is a host-only URL that looks like this: http://www.sitegenesis.com/.

     • If the rule specifies a pipeline property value, forward the request to the pipeline using the pipeline, locale, and params properties.
     • If the rule specifies a host property value, redirect to the specified host.
     • If the rule provides a path, construct a redirect URL by appending the value from the provided path parameter to the value of the host property. If no value is configured for the host property, ignore the path property.
     • If the rule doesn't provide any parameters, forward the request to the Default-Start pipeline.

   • No - the entered URL contains at least a partial path and looks like this: http://www.sitegenesis.com/electronics

     • If the rule provides a host property value, replace the URL host with the host value and use the rest of the path in the entered URL to construct a 301 redirect.
     • If the rule provides a path but no host property value, the path value is ignored.

Generating Storefront URLs

When generating storefront URLs, B2C Commerce adds the appropriate site path to the generated URL. B2C Commerce determines the site path in the following way for a given hostname and locale. If the settings property specifies a value for the site-path property, B2C Commerce uses the specified value as the site path for the default locale (the configured default locale for the site). If the settings property doesn't specify a value for the site-path property, B2C Commerce uses the value of the locale property (or the locale property plus the if-site-path property) to determine the site path, as follows:

• If a mapping rule specifies an if-site-path property but doesn't specify a locale property, the value of the if-site-path property is used as the site path for the default locale.
• For all other locales, the first if-site-path rule with the specified locale determines the site path. (An empty site path is possible with a locale-only rule, if it is the first rule for this locale.)
• Activated site locales that are not configured in mappings use the mapping for default locale. If the default locale is not defined, then the site path is empty.