Optimize URLs for search engines

This section describes how custom widgets can invoke an /assembler endpoint to generate URLs that are optimized for search engines.

The optimization not only increases the rankings of the URLs in search engine results. It also makes the URLs more descriptive of the contents of the pages and thus more intelligible to shoppers.

When URLs are optimized, the display labels of the refinements to which a shopper navigates are converted into keywords. The keywords are organized into a directory-style path that becomes part of the URL. Any search terms entered by the shopper are appended to the URL.

For example, the following optimized URL points to a page that a shopper reaches by performing a search on the term “xbox” and then selecting the refinement “Consoles”:

https://www.example.com/searchresults/Consoles/_/N-1817514100?Ntt=xbox

where:

Consoles is the display label for the dimension value with the ID 1817514100.

Ntt=xbox specifies the record search term entered by the shopper (“xbox”).

By default, only the Brand dimension and the Category dimension and its hierarchy are included in optimized URLs. For information about how to include additional dimensions in optimized URLs, see Specify which dimensions are included in optimized URLs.

To turn on SEO URL optimization for search URLs, you must first use the Admin API to issue a PUT request to /ccadmin/v1/merchant/clientConfiguration that sets the useEnhancedSearch property to true. The useEnhancedSearch property is set to false by default.

Optimize URLs through custom widgets

You create optimized URLs from within a custom widget by calling the URL optimization API. For detailed information about how to create custom widgets, see Understand widgets. Note that the standard widget types do not optimize URLs.

Pages pointed to by the optimized URLs can include links to refinements of the current navigation state. When a shopper clicks a refinement, the custom widget generates an optimized URL and renders that page, which can contain a link to a further refinement, and so on. Thus, a shopper can navigate from page to page following a sequence of optimized URLs.

For example, if a shopper searches on the keyword “xbox”, the custom widget executes the following endpoint and displays the corresponding page:

/ccstoreui/v1/assembler/pages/Default/services/guidedsearch?Ntt=xbox

This endpoint returns JSON containing a link to a refinement of “xbox”; for example, “Consoles”:

{
        "@type": "RefinementMenu",
        "displayName": "Category",
        "name": "product.category",
        "ancestors": [],
        "dimensionName": "product.category",
        "refinements": [
          {
            "link":
              "/Consoles/_/N-1817514100?Ntt=xbox",
              "label": "Consoles",
          },
          ...
        ]
      }

When this JSON is rendered, the shopper can click the refinement “Consoles” to advance to the next page.

The following steps illustrate in detail how custom widgets can generate a sequence of optimized URLs that reflect a shopper’s selection of refinements:

When a shopper navigates to a refinement or enters a keyword search term, the custom widget executes a GET operation on the following endpoint:
```
/ccstoreui/v1/assembler/pages/Default/{pagePath}/{miscPath}/{pathSeparatorToken}/{pathParameters}?{queryString}
```
where:

pagePath = Indicates the page to which the URL points.

miscPath = Keywords representing dimension value IDs, arranged into a directory-style structure.

pathSeparatorToken = An arbitrary token (an underscore by common convention) that separates the optimized portion of the URL from the query parameters that the optimized portion represents.

pathParameters = The dimension IDs in the current navigation state, prefixed by the query parameter N-.

queryString = The search terms that the shopper enters, prefixed by the query parameter Ntt-.

Note: Default is the required site ID.
The widget renders the JSON as a refinement menu for the dimension specified by dimensionName. The refinement’s display name is specified by the label property.
When the shopper selects the refinement, the custom widget constructs a search service URL consisting of the “link" value appended to the following prefix: "/ccstoreui/v1/assembler/pages/Default/guidedsearch".
Thus, when a shopper searches on the keyword “xbox” and then clicks the refinement Consoles, the widget constructs an optimized URL such as the following:
```
/ccstoreui/v1/assembler/pages/Default/guidedsearch” + /Consoles/_/N-1817514100?Ntt=xbox
```
The custom widget renders the page pointed to by the above URL. If the shopper chooses any further refinements, the widget again executes the URL optimization API and constructs and renders a URL for the refinement page.

Note: Shoppers see optimized URLs such as the following in their browsers:

http://www.example.com/products/consoles/_/N-1817514100?Ntl=en&Ntt=xbox

They do not see the search URLs such as the following, which the custom widgets construct behind the scenes and invoke through a GET operation:

http://www.example.com/ccstoreui/v1/assembler/pages/Default/services/guidedsearch/consoles/_/N-1817514100+927940346?Ntl=en&Ntt=xbox

Specify which dimensions are included in optimized URLs

By default, only the Brand dimension, the Category dimension, and dimensions in the Category hierarchy are included in optimized URLs.

You can specify additional dimensions to appear in the URLs by setting the includeInNavLinks property of the dimension’s seoConfig attribute. If this property is set to true, the dimension is included in navigation URLs. (Navigation URLs point to pages that a shopper arrives at by guided navigation.)

Recommended practice is to include dimensions that describe the qualities of products that shoppers are likely to search for (such as category, brand, fabric, or features) and to exclude dimensions with numerical values (such as rating, price or weight).

Note: For example, the seoConfig attribute of the color dimension can be configured as follows:

"product.color": {
     "ecr:type": "dimension",
     "mergeAction" : "update"
     ...
     "seoConfig": {
        "includeInNavLinks": true
     },
    ...
}

In the example above, "includeInNavLinks": true causes the dimension color to be included in navigation URLs.

Note: Include the "mergeAction" : "update" property if the dimension attribute already exists in Oracle Commerce. For a dimension that you are creating, omit the "mergeAction" : "update" property. (add is the default mergeAction value.)

To apply your configuration of optimized URLs, execute the following endpoint:

POST | PUT /gsadmin/v1/${appName}/attributes/system