---
title: Spotlight content rules for product listing pages
slug: q1eg0220
canonical_url: https://docs.coveo.com/en/q1eg0220/
collection: coveo-merchandising-hub
source_format: adoc
---
# Spotlight content rules for product listing pages

> **Important**
>
> Contact your Coveo representative to enable spotlight content rules in your [Coveo organization](https://docs.coveo.com/en/185.md).

In the [Product listings manager](https://docs.coveo.com/en/p64e0262.md) of the [Coveo Merchandising Hub (CMH)](https://docs.coveo.com/en/o5290573.md), merchandisers can define _spotlight content_ ranking rules to insert non-product content into specific positions on one or more [product listing pages (PLPs)](https://docs.coveo.com/en/m1sf3187.md).

![Spotlight content rule configuration in Product Listings | Coveo Merchandising Hub](https://docs.coveo.com/en/assets/images/coveo-for-commerce/images/cmh/cmh-listings-spotlight-content-rule.png)

> **Note**
>
> For spotlight content to appear on your [storefront](https://docs.coveo.com/en/p33g0410.md), your implementation must render it.
> Developers can enable and display spotlight content using the [Headless library](https://docs.coveo.com/en/o52e9091.md) (see [displaying spotlight content](https://docs.coveo.com/en/o8ce0239.md#displaying-spotlight-content)) or by [using the Commerce API directly](https://docs.coveo.com/en/p5je0317.md#retrieve-mixed-product-and-spotlight-content-results).

## Use case examples

Spotlight content ranking rules help address a variety of use cases.
Examples include:

* **Spotlight product-related information**: Provide a link to a page with information about a particular product category, such as a buying guide or a sizing guide.

* **Spotlight a specific brand**: Provide a link to a [product listing page (PLP)](https://docs.coveo.com/en/m1sf3187.md) that only shows products from a specific brand.

* **Spotlight a site-wide campaign**: Provide a link to a page with information about a site-wide promotion or campaign, such as free shipping or a list of payment options.

## Spotlight content and pins

Spotlight content rules can affect the visual merchandising of your [product listing pages (PLPs)](https://docs.coveo.com/en/m1sf3187.md) by changing the order of the numbered positions that are reserved by [pin rules](https://docs.coveo.com/en/o5sf0214.md).
Although spotlight content can't come into direct [conflict with a pin](https://docs.coveo.com/en/o5sf0214.md#pin-rule-conflicts), it will “push” a pinned product in a numbered position over from its expected output on the PLP.

These rules don't reserve specific numbered positions on the PLP because spotlight content isn't considered a product and doesn't have a product ranking.
Instead, a spotlight content rule creates a new unnumbered position before a particular numbered position and “pushes” the numbered position over by one.
That numbered position keeps its ranking number.

**Example**

The “GPS Fish Finders” PLP includes the following products in these numbered positions:

| 1 | 2 | 3 (reserved) | 4 |
|---|---|---|---|
| `FishDarmin` | `Gpshum` | `Navify` | `Lowrance` |

The `Navify` fish finder is a product that's pinned at position 3.
You create a spotlight content rule that inserts a fish finder buying guide before product 3.
This creates a new unnumbered position between positions 2 and 3.

| 1 | 2 |  | 3 (reserved) |
|---|---|---|---|
| `FishDarmin` | `Gpshum` | Fish finder buying guide | `Navify` |

The `Navify` fish finder is still pinned at position 3, but on the PLP, the buying guide is the third item and the `Navify` fish finder is the fourth item.
## Prerequisites

Before you create rules in the [Coveo Merchandising Hub (CMH)](https://docs.coveo.com/en/o5290573.md):

* [Create query pipelines](https://docs.coveo.com/en/o48e0216.md#storefront-associations-and-query-pipelines).

* [Choose the correct property](https://docs.coveo.com/en/o6lb0453.md#property-and-locale-selectors) to ensure that your changes affect the intended listing pages.

## Create spotlight content rules

To create spotlight content rules

1. In the CMH, select **Product listings**.

1. From the navigation tabs, select **ranking rules** and then click **Create ranking rule**.

1. Under **This rule will apply to**, define the scope of the rule.

   1. **Locale**: Select the [locale](https://docs.coveo.com/en/p4tf0351.md) that the spotlight content rule applies to.
By default, a rule applies to all available [locales](https://docs.coveo.com/en/p4tf0351.md).

   1. **Audiences**: Select the audience that the spotlight content rule will target.
You can choose between predefined audience profiles or create custom profiles.
You can only select one audience profile per rule.

    * **All visitors**: By default, the rule applies to all [visitors](https://docs.coveo.com/en/nbub9475.md).

    * **Device & technology**: Target [visitors](https://docs.coveo.com/en/nbub9475.md) visiting a [storefront](https://docs.coveo.com/en/p33g0410.md) using a specific device type.
The device type is determined by the information sent by the [visitor](https://docs.coveo.com/en/nbub9475.md)'s browser, not by the device's screen size.
Available options are:

      * **Desktop**: Encompasses desktop computers and laptops.

      * **Mobile**: Encompasses all mobile phones.

      * **Tablet**: Encompasses all tablets.

    * **Visitor type**: Target the [visitors](https://docs.coveo.com/en/nbub9475.md) who are logged into the [storefront](https://docs.coveo.com/en/p33g0410.md) or those who aren't.

    * **Your audiences**: Create a custom audience profile that you can reuse in other rules sharing the same [property](https://docs.coveo.com/en/p4ue0547.md).
After a custom audience profile is created, it can't be changed once the rule is published.
If all rules containing a custom audience profile are deleted, the custom audience profile will no longer be available as an option when creating new rules.

      * **Visitor URL**: Target [visitors](https://docs.coveo.com/en/nbub9475.md) based on the URL of the [storefront](https://docs.coveo.com/en/p33g0410.md) page they're on.

      * **Referrer URL**: Target [visitors](https://docs.coveo.com/en/nbub9475.md) based on the URL they came from before landing on the [storefront](https://docs.coveo.com/en/p33g0410.md).

        > **Important**
        >
        > For URL-based audiences to function correctly with query parameters (such as campaign tracking parameters like `?brand=barca&model=sp&color=red`), you can pass the complete URL including query parameters to Headless or the Commerce API directly.
        > See [Navigating between pages (CSR)](https://docs.coveo.com/en/o7v87331.md), [Build product listing pages (SSR)](https://docs.coveo.com/en/p25b0072.md), and [Use the Commerce API directly](https://docs.coveo.com/en/p5je0317.md#retrieve-products-for-a-listing-page) for implementation details.

        > **Note**
        >
        > Flexible audience targeting for [product listing pages](https://docs.coveo.com/en/m1sf3187.md) requires the Public Listing Page API and Query Configurations API.
        > If your [Coveo organization](https://docs.coveo.com/en/185.md) still uses the legacy search or listing configuration APIs, migrate first.
        > See [Search and listing configuration APIs deprecation](https://docs.coveo.com/en/q4dd0300.md).

   1. [.initial]**listing page**: Choose whether the spotlight content rule applies to all listing pages or to one or more specific listing pages.

    * To apply the spotlight content rule to all listing pages:

         1. Select **All listing pages**.
You won't be able to select an operator or any specific listing pages.

         1. Click **Apply**.

    * To apply the spotlight content rule to specific listing pages:

         1. Select **Specific listing pages**.

         1. Select an **Operator**.

        * `Is`: This operator identifies listing pages that exactly match the specified value.
For example, you can use it to create a rule that only targets the listing page `accessories`.

        * `Page name contains`: This operator identifies listing pages where the specified value is found within the full value of the listing page name.
For example, you can use it to create a rule that targets all listing pages whose name contains the term `accessories`, including `Accessories|Bags` and `Accessories|Life Jackets`.

        * `Page URL contains`: This operator identifies listing pages where the specified value is found within the full value of the listing page URL.
For example, you can use it to create a rule that targets all listing pages whose URLs contain the term `kayak`, including `sports.barca.group/plp/canoes-kayaks` and `sports.barca.group/plp/canoes-kayaks/kayaks/sea-kayaks`.

         1. Select one or more [.initial]**listing pages** that the spotlight content rule applies to.

         1. Click **Apply**.

1. Under **Select an action**, select **Spotlight content**.

1. On the **Layout** card, select the position in which you want to insert the spotlight content.
This position is relative to a particular product.
For example, if you want the spotlight content to appear in the third position on the listing pages you selected, insert it before product 3.

1. On the **Assets** card, define the spotlight content that you want to insert:

   1. Under **Desktop image**, enter the URL of an image that you want users on desktop browsers to see.
Check the **Use same image for mobile** box if you want desktop and mobile users to see the same image.

   1. (Optional) Under **Mobile image**, enter the URL of an image that you want users on mobile browsers to see.

   1. (Optional) Under **Accessibility**, add a short alternative text description of the image so that people using assistive technologies can understand what it shows.

   1. Under **URL**, enter the address to which you want to send users when they click the spotlight content.

   1. (Optional) Under **Heading**, enter a heading or title for your spotlight content.

   1. (Optional) Under **Subheading**, enter any other text that you want to appear with your spotlight content.

   1. (Optional) When you set a heading or subheading, use **Heading font color** and **Subheading font color** to set their colors (for example, a hex value such as `#000000`).

1. Click **Apply**.

1. Review your rule configuration.

   > **Leading practices**
   >
   > Use the panel on the right to preview how the rule affects
   > the products on the listing page for a given [locale](https://docs.coveo.com/en/p4tf0351.md).
   >
   > The preview is an approximate simulation that won't cover every scenario encountered in a live environment.
   >
   > An [icon](https://docs.coveo.com/en/ncce0176.md#preview-indicators) appears on the product card to indicate whether the rule affects the product.

1. Click **Next**.

1. Under **Rule name**, enter a meaningful name for your rule.

1. Under **Choose when to publish**, select one of the following:

  * To apply the rule immediately, select **Publish now**.

  * To set a schedule for the rule, select **Set a schedule**, and then select the time frame in which the rule should apply.

1. Click **Publish**.

Once published, the rule will take effect on the storefront within a minute or at the scheduled time.

## Modify spotlight content rules

To modify spotlight content rules

1. In the CMH, select **Product listings**.

1. From the navigation tabs, select **ranking rules**.

1. Locate the rule that you want to modify.

1. Click [dots], and then click **Edit**.

1. You can modify the rule's scope (**Locale**, **Audiences**, or [.initial]**listing page**) or its configuration by clicking **Edit** on the relevant card.
These are the same settings covered in the [rule creation](#create-spotlight-content-rules) section.

1. When you've finished editing the rule, or to modify its publishing settings, click **Next**.

1. Update the publishing settings, if applicable, and then click **Publish**.

Once published, the modified rule will take effect on the storefront within a minute or at the scheduled time.

## Copy spotlight content rules

To copy spotlight content rules

1. In the CMH, select **Product listings**.

1. From the navigation tabs, select **ranking rules**.

1. Locate the rule that you want to copy.

1. Click [dots], and then click **Copy to...**.

1. In the **Copy rule** modal that opens, you can choose whether to copy the rule to other [properties](https://docs.coveo.com/en/p4ue0547.md) or listing pages.
If the rule applies to all listing pages, you won't see the option to copy the rule to other listing pages.

  * To copy the rule to other [properties](https://docs.coveo.com/en/p4ue0547.md):

      1. Select **Property** and click **Next**.

      1. Use the dropdown menu to select one or more [properties](https://docs.coveo.com/en/p4ue0547.md).

         > **Important**
         >
         > If the rule is scoped to one or more listing pages that
         > don't exist in the target [property](https://docs.coveo.com/en/p4ue0547.md), you'll see an error message and be unable to proceed with the copy.
         >
         > The error message will list the listing pages that are missing from the destination [property](https://docs.coveo.com/en/p4ue0547.md).

      1. Click **Confirm copy**.

  * To copy the rule to other listing pages (if applicable):

      1. Select [.initial]**listing page** and click **Next**.

      1. Use the dropdown menu to select one or more listing pages.

      1. Click **Confirm copy**.

The rule is copied to the target [properties](https://docs.coveo.com/en/p4ue0547.md) or listing pages.

## Delete spotlight content rules

To delete spotlight content rules

1. In the CMH, select **Product listings**.

1. From the navigation tabs, select **ranking rules**.

1. Locate the rule that you want to delete.

1. Click [dots], and then click **Delete**.

1. Click **Delete** again to confirm.

The rule is deleted.