Optimize URLs for search engines
This section describes how custom widgets can invoke an /assemble
r 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 parameterN-
.queryString
= The search terms that the shopper enters, prefixed by the query parameterNtt-
.Note:
Default
is the required site ID. - The widget renders the JSON as a refinement menu for the
dimension
specified bydimensionName
. The refinement’s display name is specified by thelabel
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