Configure Keyword Redirects

This section describes keyword redirects and how to export, create, replace, and modify keyword redirect configuration using the Search Admin and Configuration REST API.

This section applies to OSF. This section applies to Open Storefront Framework (OSF).

It includes the following topics:

Understand Keyword Redirects

You can configure your application to send a storefront shopper to a particular URL when the shopper enters a particular search term. The URL can represent a static page in your application (such as an “About Us” page) or a specific search or navigation state. This type of configuration is known as a keyword redirect.

You can configure any number of search terms to redirect the shopper to a particular URL. For example, you can configure the search terms “delivery” and “shipping” to redirect shoppers to a URL such as http://shipping.example.com.

Configure Keyword Redirects for Multiple Sites

If your instance of Retail Digital Commerce is running multiple sites, you can configure keyword redirects differently for the different sites by using the siteIds attribute. A redirect entry created without the siteIds attribute applies to all sites.

Keyword Redirect Objects

Keyword redirects are configured by the following three ecr:type objects:

  • a redirects object, which contains a single:
  • redirect-group object, which contains one or more of the following objects:
    • redirect-entry objects, each of which specifies the URL to which shoppers are redirected when they enter a particular search term.
    • Multiple redirect-entry objects, each specifying a different search term, can redirect shoppers to the same URL.

Note:

It is possible to configure more than one redirect-group object, but for all ordinary purposes a single redirect-group object is sufficient.

Sample redirects configuration

The following example illustrates the configuration of a redirects object containing a redirect-group object named Products, which contains redirect-entry objects named id1 and id2: 

{
    "ecr:type": "redirects",
    "Products" : {
        "ecr:type": "redirect-group",
        "id1" : {
          "ecr:type": "redirect-entry",
          "searchTerms": "canon",
          "matchmode": "MATCHEXACT",
          "url": "/browse/Canon/_/N-1z141ya"
        },
        "id2" : {
          "ecr:type": "redirect-entry",
          "searchTerms": "nikon",
          "matchmode": "MATCHEXACT",
          "url": "/browse/Nikon/_/N-1z141ya"
      }
    }
}

Configure the Redirects Object

This section describes the operations that can be performed to export, create, replace, and modify configuration of the redirects object.

Redirects object attribute

The following table summarizes the attribute of redirects objects.

Attribute Required? Type Values
"ecr:type" yes String

Redirects (required value)

There can be only one redirects object. The redirects object can contain one or more redirect-group objects.

See Sample redirects configuration.

Note:

You cannot add attributes to or modify the attribute value of the redirects object. You can only create it, if for any reason it is missing.

Export redirects object in JSON format

Use the following endpoint to export configuration of the redirects object, in JSON format: 

GET /gsadmin/v1/cloud/redirects.json

In JSON format, the GET endpoint returns full configuration of the redirects object, and lists the child object, Default, of the redirects object; for example: 

{
  "ecr:lastModifiedBy": "occ_admin",
  "ecr:lastModified": "2016-10-26T09:32:32.602-07:00",
  "ecr:createDate": "2016-10-26T09:32:32.602-07:00",
  "ecr:type": "redirects",
  "Default": {
    "ecr:lastModifiedBy": "occ_admin",
    "ecr:lastModified": "2016-10-26T09:32:32.661-07:00",
    "ecr:createDate": "2016-10-26T09:32:32.661-07:00",
    "ecr:type": "redirect-group"
  }
}

To export the full configuration of the child object of the redirects object, use the GET method in ZIP format, as described in the following section.

Export redirects object in ZIP format

Use the following endpoint to export configuration of the redirects object in ZIP format: 

GET /gsadmin/v1/cloud/redirects.zip

In ZIP format, the GET endpoint returns not only the redirects object, but also the immediate child object (redirect-group) of redirects.

The configuration of all objects is returned in a ZIP file. The ZIP file includes a file named _.json containing the configuration of the redirects object, and an additional _.json file containing partial configuration of the redirect-group object.

For example, suppose that the redirects object contains a redirect-group named Default. The _.json file that configures the redirects object contains the following: 

{
  "ecr:lastModifiedBy": "admin",
  "ecr:lastModified": "2016-10-17T05:25:35.760-07:00",
  "ecr:createDate": "2016-10-17T05:25:35.760-07:00",
  "ecr:type": "redirects"
}

The _.json file that configures the redirect-group object named Default is contained in a directory named Default within the ZIP file. This _.json file contains configuration such as the following: 

{
  "ecr:lastModifiedBy": "admin",
  "ecr:lastModified": "2016-10-24T07:57:48.924-07:00",
  "ecr:createDate": "2016-10-24T07:57:48.924-07:00",
  "ecr:type": "redirect-group"
}

To get full configuration of a redirect-group object, specify the following endpoint: 

GET /gsadmin/v1/cloud/redirects/redirect-group-name.zip pathname/filename.zip

Create a redirects object

Use the following endpoint to configure the redirects object, in JSON format or ZIP format: 

POST /gsadmin/v1/cloud/redirects

For most purposes, it is convenient to configure all child objects of redirects through the same request that configures redirects.

For example, the POST endpoint above can import the following JSON content to configure not only the redirects object, but also a redirect-group object named Default and a redirect-entry object named id1 within the redirect-group object: 

{
  "ecr:type": "redirects",
  "Default": {
    "ecr:type": "redirect-group",
    "id1": {
      "ecr:type": "redirect-entry",
      "searchTerms": "fujifilm",
      "siteIds":  "siteA",
      "matchmode": "MATCHEXACT",
      "url": "http://www.example.com/about-us"
      }
    }
}

Replace the redirects object and its children

In JSON format, use a PUT endpoint to replace the redirects object and all its child objects with the content provided as input to the endpoint: 

PUT /gsadmin/v1/cloud/redirects

Note:

The PUT method cannot be used with ZIP format.

In ZIP format, use a POST endpoint to replace the redirects object and all its child objects with the content provided as input to the endpoint: 

POST /gsadmin/v1/cloud/redirects

For example, the PUT and POST endpoints above can import the following JSON content to replace all existing configuration of the redirects object and its child objects: 

{
  "ecr:type": "redirects",
  "Default": {
    "ecr:type": "redirect-group",
    "id1": {
      "ecr:type": "redirect-entry",
      "searchTerms": "kodak",
      "matchmode": "MATCHEXACT",
      "url": "http://www.example.com/about-us"
    }
  }
}

Configure a Redirect-group Object

This section describes how to get, create, modify, and replace the configuration of a redirect-group object.

Redirect-group object attributes

The following table lists the attributes of a redirect-group object:

Attribute Required? Type Values
"ecr:type" yes String

redirect-group (required value)

Note: For almost all purposes, only one redirect-group object needs to be configured. Each redirect-group object, however, can contain one or more redirect-entries child objects.

See Sample redirects configuration.

Export the redirect-group object in ZIP format

Use an endpoint of the following form to export configuration of a redirect-group object in ZIP format: 

GET /gsadmin/v1/cloud/redirects/redirect-group-name.ZIP

The ZIP file in which the configuration is downloaded contains the following _.json files:

  • A file containing the configuration of the redirects object; for example: 
{
  "ecr:lastModifiedBy": "occ_admin",
  "ecr:lastModified": "2016-10-26T17:11:47.308Z",
  "ecr:createDate": "2016-10-26T09:32:32.602-07:00",
  "ecr:type": "redirects"
}
  • An individual _.json file for the redirect-group object in redirects; for example, the configuration of the Default redirect-group object can be as follows: 
{
  "ecr:lastModifiedBy": "occ_admin",
  "ecr:lastModified": "2016-10-26T10:11:47.369-07:00",
  "ecr:createDate": "2016-10-26T10:11:47.369-07:00",
  "ecr:type": "redirect-group",
  "id1": {
    "ecr:type": "redirect-entry",
    "searchTerms": "canon",
    "matchmode": "MATCHEXACT",
    "url": "http://www.example.com/about-us",
    "searchTermExpansions": {
      "0":{"canon": ["canon"]}
    }
  },
  "id2": {
    "ecr:type": "redirect-entry",
    "searchTerms": "contacts",
    "matchmode": "MATCHEXACT",
    "url": "/contact-us",
    "searchTermExpansions": {
      "0": {"contacts": ["contact"]}
    }
  }
}

Note:

searchTermExpansions is a system-generated attribute. Do not delete or modify it except when the searchTerms attribute is updated, in which case delete the searchTermExpansions attribute from the JSON, use the PUT endpoint to update the redirect-group object and generate a new searchTermExpansions attribute.

Export the redirect-group object in JSON format

Use an endpoint of the following form to export configuration of a redirect-group object in JSON format:

GET /gsadmin/v1/cloud/redirects/redirect-group-name.json
or
GET /gsadmin/v1/cloud/redirects/redirect-group-name

For example, the following endpoint exports configuration of a redirect-group named Default: 

GET /gsadmin/v1/cloud/redirects/Default

The following sample illustrates content of the file to which the configuration of the Default redirect-group object is exported; note that the configuration of the two redirect-entry child objects under Default is contained in this same file:

{
  "ecr:type": "redirect-group",
  "id1": {
    "ecr:type": "redirect-entry",
    "searchTerms": "canon",
    "matchmode": "MATCHEXACT",
    "url": "http://www.example.com/about-us",
    "searchTermExpansions": {
      "0": {"canon": ["canon"]}
    }
  },
  "id2": {
    "ecr:type": "redirect-entry",
    "searchTerms": "contacts",
    "matchmode": "MATCHEXACT",
    "url": "/contact-us",
    "searchTermExpansions": {
      "0": {"contacts": ["contact"]}
    }
  }
}

Note:

searchTermExpansions is a system-generated attribute. Do not delete or modify it except when the searchTerms attribute is updated, in which case delete the searchTermExpansions attribute from the JSON, use the PUT endpoint to update the redirect-group object and generate a new searchTermExpansions attribute.

Create the redirect-group object

If no redirect-group object currently exists, you can create one using the POST method. If a redirect-group object currently exists, however, you do not need to create another. One redirect-group object is sufficient for all ordinary purposes.

Use a POST endpoint of the following form to create a redirect-group object, in JSON format or ZIP format: 

POST /gsadmin/v1/cloud/redirects/redirect-group-name

The JSON content that configures the redirect-group object can include the configuration of the redirect-entry objects that the redirect-group is to contain; for example, the following content supplied to the POST endpoint above creates a redirect-group object containing two redirect-entry objects, id1 and id2: 

{
  "ecr:type": "redirect-group",
  "id1": {
    "ecr:type": "redirect-entry",
    "searchTerms": "canon",
    "matchmode": "MATCHEXACT",
    "url": "http://www.example.com/about-us",
    "searchTermExpansions": {
      "0": {"canon": ["canon"]}
    }
  },
  "id2": {
    "ecr:type": "redirect-entry",
    "searchTerms": "contacts",
    "matchmode": "MATCHEXACT",
    "url": "/contact-us",
    "searchTermExpansions": {
      "0": {"contacts": ["contact"]}
    }
  }
}

Configure a Redirect-entry Object

You can get, create, modify, and replace redirect-entry object configuration using the Search Admin and Configuration REST API.

Export redirect-entry object configuration in ZIP format

Use a GET endpoint of the following form to export configuration of a redirect-entry object in ZIP format: 

GET /gsadmin/v1/cloud/redirects/redirect-group-name/redirect-entry-name.ZIP

The ZIP file in which the configuration is downloaded contains a file named _.json that contains the configuration of the redirect-entry object.

Export redirect-entry object configuration in JSON format

Use a GET endpoint of the following form to export configuration of a redirect-entry object in JSON format: 

GET /gsadmin/v1/cloud/redirects/redirect-group-name/redirect-entry-name

For example, the following GET endpoint exports the configuration of a redirect-entry object named ID3: 

GET /gsadmin/v1/cloud/redirects/Default/ID3

The following JSON content illustrates configuration of a redirect-entry object that can be exported by the endpoint above: 

{
  "ecr:type": "redirect-entry",
  "searchTerms": "fujifilm",
  "matchmode": "MATCHEXACT",
  "url": "http://www.example.com/about-us",
  "searchTermExpansions": {"0": {"fujifilm": ["fujifilm"]}}
}

Create a redirect-entry object

In JSON or ZIP format, use the following POST endpoint to configure a specified redirect-entry object in a specified redirect-group object: 

POST /gsadmin/v1/cloud/redirect/redirect-group-name/redirect-entry-name

For example, the following endpoint configures a redirect-entry object named id3 in a redirect-group named Default: 

POST /gsadmin/v1/cloud/redirect/Default/id3

The following code illustrates the configuration of a redirect-entry object that can be input to an endpoint in either ZIP or JSON format: 

{
  "ecr:type": "redirect-entry",
  "searchTerms": "fujifilm",
  "matchmode": "MATCHEXACT",
  "url": "http://www.example.com/about-us"
}

Modify a redirect-entry object

In JSON format, you can use the following endpoint to modify the configuration of a specified redirect-entry object in a specified redirect-group object: 

PATCH /gsadmin/v1/cloud/redirects/redirect-group-name/redirect-entry-name

Note: The PATCH method cannot be used in ZIP format.

For example, the following endpoint modifies a redirect-entry object named id3 in a redirect-group object named Products: 

PATCH /gsadmin/v1/cloud/redirects/Products/id3

The endpoint above can use JSON content such as the following to modify the url attribute of redirect-entry object named id3: 

{
  "ecr:type": "redirect-entry",
  "url": "http://www.example.com/about-us"
}

Redirect-entry object attributes

The following table lists the attributes of redirect-entry objects.

Attribute Required? Type Description
"ecr:type" yes String

redirect-entry

Note: One or more redirect-entry objects can be configured as child objects of a single redirect-group object.

See Sample redirects configuration.

searchTerms yes String One or more phrases to be compared with search terms entered by shoppers. When matches occur between a searchTerms value and a search term entered by a shopper, the keyword redirect is triggered.
matchmode yes String

The type of match between the specified searchTerms value and the search term that the user enters. Must be one of:

MATCHEXACT – The keyword redirect is triggered only if a shopper’s search terms exactly match the specified searchTerms values, in the same order, with no additional terms.

MATCHPHRASE – Default. The keyword redirect is triggered if the shopper’s search terms match the specified searchTerms values, in the same order. The shopper’s search terms may include additional words before or after the searchTerms values.

MATCHALL – The keyword redirect is triggered if a shopper’s search terms exactly match the specified searchTerms values, with no additional terms, but not necessarily in the same order

url yes String The URL to which users are redirected when a search term entered by a shopper matches a searchTerms value.
siteIds no Array of Strings Specifies one or more site IDs that this redirect entry belongs to. A redirect entry created without the siteIds attribute applies to all sites.
enableStemming no Boolean Determines whether the system considers the stems of search terms (for example, “box” the stem of “boxes”) when constructing keyword redirects.
searchTermExpansions no object A system-generated attribute