Shopping Tab

This page assumes that:

• You want to serve Search Expander product ads in a shopping results tab or page
• You have set up a Search Expander account and search engine
• You have followed the guide to integrating Search Expander's standard widgets

Integrating the Search Expander shopping results is similar to integrating the standard widgets.

The shopping widget is expected to be rendered on a separate tab or page from your web search results. On this shopping route, you will need to do the following:

• Add some markup to your shopping results page
• Load the Search Expander JavaScript library on the page
• Call the global sxpr.shopping() JavaScript function

Markup

You must provide an HTML block element somewhere in your shopping route's content with the attribute data-sxpr-shopping. This container will have the following elements rendered inside it:

• Mainline product links
• A carousel of sponsored product links above the mainline products
• An optional carousel of eco-friendly product links above the mainline products
• Inputs for filtering and sorting the products
• A tree of product categories
• Pagination buttons for the mainline products

The shopping widget is mobile-friendly, but its container should be placed in a layout context which allows for a sizeable amount of content (e.g. a sidebar would be inappropriate).

Load the Search Expander library

You can include the Search Expander JavaScript library using:

<script src="https://cdn.searchexpander.com/js/sxpr.js"></script>

Call sxpr.shopping()

To run Search Expander, call sxpr.shopping() after the script has loaded:

sxpr.shopping({
    se: 'your-search-engine-id', // Replace 'your-search-engine-id' with your search engine's ID
    // ... other settings here
});

Search query

Search Expander needs to know your user's search query in order to provide relevant shopping results. You can provide the search query in one of these ways:

• Pass a q value to sxpr.shopping() (this is the most direct method)
• Add the data-sxpr-input attribute to a search input whose value is the search query
• Pass a searchInput value to sxpr.shopping() which references a search input whose value is the search query
• Pass a shoppingUrlTemplate string to sxpr() and sxpr.shopping() (see below)

JavaScript example

sxpr.shopping({
    se: 'your-search-engine-id',
    q: 'lorem ipsum',
    // Or alternatively:
    searchInput: document.getElementById('my-search-input'),
});

HTML example

<input name="q" value="lorem ipsum" data-sxpr-input>

Empty search queries

Unlike the other Search Expander widgets, the shopping widget will be functional even without a user search query. If no search query is provided and cannot be derived from the page's search inputs or URL, the widget will render without any product links but will provide a tree of product categories in a sidebar. Users can click on these categories in order to initiate product searches.

Linking to your shopping results

The Search Expander widgets for general web search results will sometimes contain links to your shopping results. In order that these links are pointing to the right place, Search Expander needs to know how to construct their URLs. To allow this, you must provide a shoppingUrlTemplate setting when calling sxpr() on your general web search results page.

For example, let's say your shopping results appear under the URL:

https://example.com/shopping

In this case, you should set shoppingUrlTemplate to:

https://example.com/shopping?q={searchTerms}.

(Note that the URL parameter name q in the above example can be anything you like.)

Relative URLs with absolute paths are allowed, for example:

/shopping?q={searchTerms}

// Run on your web results page:
sxpr({
    se: 'your-search-engine-id',
    shoppingUrlTemplate: 'https://example.com/shopping?q={searchTerms}',
    // ... other settings here
});

The {searchTerms} tag will be automatically replaced with the user search query, which will be sent to the Search Expander API to obtain relevant products.

(Passing shoppingUrlTemplate to sxpr.shopping() in addition to the above is not strictly necessary but can help Search Expander figure out the user search query if q is not set.)

Dynamic control of shopping route links

If navigating to the shopping route on your site is initiated by JavaScript code rather than standard page navigation (e.g. in a SPA), you may need to use JavaScript to handle clicks on shopping route links, rather than relying on normal links. You can do this by setting a handleShoppingClick function on the sxpr() settings object. This function can take care of updating the page so that the user is navigated to the shopping results.

Note that handleShoppingClick will need to be passed to sxpr() on your web results route, rather than to sxpr.shopping() on the shopping route.

If you provide a handleShoppingClick function, then when a widget shopping route link is clicked, the link's default behaviour will be overridden and the function will be left to handle the shopping results request.

handleShoppingClick is passed an object with the following interface:

{
    q: string;                  // The shopping search query
    origQ: string;              // The original user query (which may not be the same as q)
    link: HTMLElement;          // The clicked link or alert button
    event: MouseEvent;          // The link's click event
    url: string | undefined;    // The shopping route's URL (only set if shoppingUrlTemplate is set)
}

You will usually only need to use the q value in this object.

Shopping route alert button

In order to alert users to the shopping route when they carry out an ad-friendly web search, you can add an alert button to your web results route. This can just be a div or span element with the attribute data-sxpr-shop-alert. For example:

<span data-sxpr-shop-alert>Shopping</span>

Clicking on this element will take the user to your shopping route, in accordance with the shoppingUrlTemplate setting. If handleShoppingClick is set, this function will be called in place of direct navigation.

Styling and behaviour will be taken care of by the Search Expander library, but of course you can tweak its appearance using CSS.

If you want the alert button hidden until shopping results are ready, add the following CSS to your page:

[data-sxpr-shop-alert] {
    display: none;
}

…and Search Expander will reveal it at the appropriate time.

Sponsored Products carousel

By default, the shopping page will display a carousel of sponsored product thumbs above the other results. If you want to disable this carousel, you must set enableSponsoredProducts to false on the object passed to sxpr.shopping(). For example:

// Run on your web results page:
sxpr.shopping({
    se: 'your-search-engine-id',
    q: 'lorem ipsum',
    
    // Add this setting to remove the Sponsored Products carousel:
    enableSponsoredProducts: false,

    // ... other settings here
});

Eco-friendly Products carousel

In addition to the Sponsored Products carousel, you have the option of adding another carousel containing a selection of eco-friendly products, where these are available. In order to enable this carousel, you must set enableEcoProducts to true on the object passed to sxpr.shopping(). For example:

// Run on your web results page:
sxpr.shopping({
    se: 'your-search-engine-id',
    q: 'lorem ipsum',
    
    // Add this setting to get a carousel of eco-friendly products:
    enableEcoProducts: true,

    // ... other settings here
});

Shopping-related settings reference

Settings for sxpr() (web search)

boolean | 'topBar' |
'knowledgePanel'

HTMLElement | string

string

(data: {
  q: string;
  origQ: string;
  link: HTMLElement;
  event: MouseEvent;
  url: string | undefined;
}) => void

Settings for sxpr.shopping() (shopping search)

HTMLElement | string

string

'small' | 'large' |
'always' | 'never'

boolean

boolean

» Styling the Widgets