---
updatedAt: 2025-03-20T20:38:44.000Z
agentTools:
  projectIndex: https://developer.sovrn.com/llms.txt
---

# Automated Comparisons

# Overview

The Automated Price Comparison allows for the dynamic insertion of price comparison widgets into web pages that contain product links facilitated by a customizable JavaScript library. It provides various options for widget types, placement, and additional configurations to enhance user interactivity and scale the price comparisons across your content.

A demo page can be found here: [Demo Automated Comparisons](https://comparisons.sovrn.com/pages/demo-automated-library.html).

# Parameters

The library accepts the following configuration options:

<Table align={["left","left","left"]}>
  <thead>
    <tr>
      <th>
        Parameter
      </th>

      <th>
        Type
      </th>

      <th>
        Description
      </th>
    </tr>
  </thead>

  <tbody>
    <tr>
      <td>
        selector
      </td>

      <td>
        string
      </td>

      <td>
        CSS selector for the target element.\
        This is often a product card that contains all the relevant information related to the featured product.
      </td>
    </tr>

    <tr>
      <td>
        urlSelector
      </td>

      <td>
        string
      </td>

      <td>
        Optional. CSS selector for the URL element.\
        This is the external URL to the product. It is often identified as an `<a>` tag.  

        * URLs provided should be direct, non-affiliated links to brands
      </td>
    </tr>

    <tr>
      <td>
        widgetPlacementSelector
      </td>

      <td>
        string
      </td>

      <td>
        CSS selector to determine where the widget should be placed.
      </td>
    </tr>

    <tr>
      <td>
        widgetSwap
      </td>

      <td>
        string
      </td>

      <td>
        Optional, method of widget placement.\
        This parameter determines how the widget should be positioned relative to the `widgetPlacementSelector`.  

        These are the available options for the `widgetSwap`:  

        `inside`: Place the widget inside a specific element.\
        `prepend`: Insert the widget at the beginning of an element.\
        `append`: Insert the widget at the end of an element.\
        `before`: Place the widget right before an element.\
        `after`: Place the widget right after an element.
      </td>
    </tr>

    <tr>
      <td>
        geolocation
      </td>

      <td>
        boolean
      </td>

      <td>
        Optional, flag to enable or disable geolocation. Enabling geolocation will present relevant merchant results based on the viewer's geolocation. By default set to `false`.
      </td>
    </tr>

    <tr>
      <td>
        resultsLimit
      </td>

      <td>
        number
      </td>

      <td>
        Optional, limits the number of results displayed. By default set to `4`.
      </td>
    </tr>

    <tr>
      <td>
        widgetType
      </td>

      <td>
        string
      </td>

      <td>
        Optional, type of widget to be used.\
        Available options are: `price-comparison`, `buttons` and `in-text`.
      </td>
    </tr>

    <tr>
      <td>
        templateId
      </td>

      <td>
        string
      </td>

      <td>
        Optional, ID of the template to use for the widget. Templates must be created here. Create a new price comparison in the platform, under “Template layout” select “Create a custom template”, style it to fit your content, and name the template. The `templateId` value will be available in the “Get code” snippet. By default is `table1`.
      </td>
    </tr>

    <tr>
      <td>
        epcSort
      </td>

      <td>
        boolean
      </td>

      <td>
        Optional, sort by EPC highest first. If true the results are sorted by EPC highest first, otherwise, the results are sorted by the default sorting. By default set to `false`.
      </td>
    </tr>

    <tr>
      <td>
        market
      </td>

      <td>
        string
      </td>

      <td>
        Optional, a supported market.\
        These are the available options for the market:  

        `gbp_en` : United Kingdom\
        `usd_en` : United States\
        `aud_en` : Australia\
        `cad_en` : Canada\
        `eur_fr` : France\
        `eur_de` : Germany\
        `eur_it` : Italy\
        `eur_nl` : Netherlands\
        `eur_es` : Spain\
        `chf_de` : Switzerland  

        NOTE:  

        The market takes priority over geolocation  

        If the market is not defined and the geolocation is set as `false`, by default the market is `usd_en`.
      </td>
    </tr>

    <tr>
      <td>
        searchKeywordsSelector
      </td>

      <td>
        string
      </td>

      <td>
        Optional, CSS selector for the keywords element.\
        The keywords took by this CSS selector will be used to make the API call by keywords.  

        NOTE:  

        `urlSelector` takes priority over `searchKeywordsSelector`
      </td>
    </tr>

    <tr>
      <td>
        priceSelector
      </td>

      <td>
        string
      </td>

      <td>
        Optional, CSS selector for the price element.\
        The price found by this CSS selector with the `delta` defined is needed to set the minimum price and the maximum price filter.  

        NOTE: the decimal is defined by the dot `.`
      </td>
    </tr>

    <tr>
      <td>
        delta
      </td>

      <td>
        number
      </td>

      <td>
        Optional, is a percentage that is used to calculate, together with the `priceSelector`, the minimum price and maximum price filter.\
        The minimum price filter is the `price` from the priceSelector - `delta` of the `price`\
        The maximum price filter is the price from the priceSelector + `delta` of the `price`
      </td>
    </tr>

    <tr>
      <td>
        showTitle
      </td>

      <td>
        boolean
      </td>

      <td>
        Optional, is a boolean value that specifies whether to display a title for the widget or not. The title will be defined by the keywords took through the `searchKeywordsSelector` . By default is set to `false`.  

        The title shown can be customized later through the CSS template.
      </td>
    </tr>

    <tr>
      <td>
        excludeSearchedMerchant
      </td>

      <td>
        boolean
      </td>

      <td>
        Optional, is a boolean value that specifies whether to remove the merchant you are searching for from the results or not. By default is set to `false`.  

        Example: if you are making a search by url by providing a Walmart product url and you specify the key `excludeSearchedMerchant` as true, we will exclude Walmart product from the results.
      </td>
    </tr>
  </tbody>
</Table>

# Usage

## Initialization

Implement the following updated Javascript on to your content with your corresponding API key (found under your platform Settings > Site).

```javascript
<script type="text/javascript">
    var vglnk = {
        key: <api key>,
        automatedLibrary: {
            selector: '.card',
            urlSelector: '.card-title a',
            widgetPlacementSelector: '.widgetDisplay',
            widgetSwap: 'inside',
            geolocation: false,                
            widgetType: 'price-comparison',
            templateId: 'table1'
        }
    };
    (function (d, t) {
        var s = d.createElement(t);
        s.type = 'text/javascript'; s.async = true;
        s.src = '//cdn.viglink.com/api/vglnk.js';
        var r = d.getElementsByTagName(t)[0];
        r.parentNode.insertBefore(s, r);
    }(document, 'script'));
</script>
```

## Validation

All the provided parameters are checked for validity.

The library will throw an error with a descriptive message if any option is invalid. Error messages generated by this library are visible in the browser's developer console.

## Creating Widgets

The widgets are dynamically created and inserted into the DOM based on the specified options.

**Notes**

* Ensure that the selectors used in options are valid and reference existing elements in the DOM. The library's functionality hinges on the correct configuration of options. Improper configuration can lead to unexpected behavior or errors.
* There is no delay when updating the fields in the custom library to when they update within the widget.
* This documentation provides a basic understanding of the AutomatedLibrary JavaScript library, outlining its structure, usage, and error handling. For further customizations or specific use cases, please contact support (<support@sovrn.com>).