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.

Parameters

The library accepts the following configuration options:

ParameterTypeDescription
selectorstringCSS selector for the target element.
This is often a product card that contains all the relevant information related to the featured product.
urlSelectorstringOptional. 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
widgetPlacementSelectorstringCSS selector to determine where the widget should be placed.
widgetSwapstringOptional, 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.
geolocationbooleanOptional, flag to enable or disable geolocation. Enabling geolocation will present relevant merchant results based on the viewer's geolocation. By default set to false.
resultsLimitnumberOptional, limits the number of results displayed. By default set to 4.
widgetTypestringOptional, type of widget to be used.
Available options are: price-comparison, buttons and in-text.
templateIdstringOptional, 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.
epcSortbooleanOptional, 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.
marketstringOptional, 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.
searchKeywordsSelectorstringOptional, 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
priceSelectorstringOptional, 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 .
deltanumberOptional, 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
showTitlebooleanOptional, 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.
excludeSearchedMerchantbooleanOptional, 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.

Usage

Initialization

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

<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 ([email protected]).