Support & F.A.Q.

For Brands: Product Locator

What is the product locator?

The product locator is an embeddable widget which can be installed on any web page. The widget displays the in-stock availability of any product nearest to the viewer's geographic location. It also allows a viewer to reserve or buy products for in-store pickup directly from local stores without leaving your site.

The widget is contained of a single line of Javascript and a single line of HTML. It will run on any web page, including secure web pages. It will attempt to fill the visible space on an HTML page as elegantly as possible.

The widget "draws" HTML on the page where it is embedded so it is very easy to style it with simple CSS.

Link to this answer

How do we add the product locator to our site for our products?

It's simple. Unless you choose to perform your own design (see below), you will be provided with a staging site with a fully working Product Locator, as determined by a design process with Locally and your team, where you can grab your codes and begin to implement.

Then, paste it on your product page (PDP) template and then make sure that product page passes either a style number, a UPC, or a set of UPCs to the embed code via the query string in the embed code.

For example, your embed code might have &style=1234 in it's query string. Just replace 1234 with the style number of the product. Alternatively, you can pass one or more UPCs to the query string, like this &upc=863538186341.

Link to this answer

What are the different Product Locator formats?

The styling for Locally's Product Locator is unlimited, but generally falls into three main formats.

Option 1: On-page

Our Product Locator can render as a robust on-page widget that presents nearby stores and product availability directly on the PDP.

ASICS: ASICS' Product Locator renders under "Want it today?" below Add to Cart. It features the two closest inventory matches or dealers to the user. Load the GEL-Kayano 24 to view. Jump to Boston, MA for inventory.

OSPREY PACKS: Osprey's Product Locator shows nearby stores and availability on the product page. Load the Atmos 65 and select a color/size to view. Jump to Austin, TX is there are no inventory matches near you.

Option 2: Button or Text Link

A simple button or text link on your PDP launches Locally's modal to show nearby product availability.

HOKA ONE ONE: HOKA's Product Locator is the "Find it Locally" button underneath Add to Cart, which launches Locally's modal. HOKA's Product Locator first shows availability, and then loads other nearby dealers. Jump to Boston, MA for rich results.

ARC'TERYX: Arc'teryx launches their Product Locator as a "Find in Store" link below Add to Cart. Load the Theta AR jacket to view. Jump to Vancouver for inventory.

UPPABABY: load the Vista and scroll down to see the orange "Find it Locally" button, which launches Locally's modal. Jump to Boston to find it in stock.

BROOKS RUNNING: Brooks loads their Product Locator as a "Check Store Availability" link below Add to Cart. Load the Levitate to view. Set your location to Boston if there is no inventory near you.

Option 3: Button + Drop-down

Many brands install a button that opens a drop-down to reveal nearby availability.

Thule: hit the blue "Find it Locally" button to reveal a drop-down showing the three nearest stores and their availability. Jump to New York City for numerous stock matches.

CamelBak: CamelBak has a custom installation. Their "Buy Locally" button is powered on their end, and swipes open a side-container in which our Product Locator is embedded, rendering as an on-page list format (see below). Jump to Austin, TX for rich results.

Link to this answer

Can we customize the style and layout of the product locator?

Your Product Locator widget will be fully customized to seamlessly match the look and feel of your site.

When launching the Product Locator, Locally's design team will provide your team with a series of concept mockups, from which you can choose your preferred approach or come up with your own. Typically, Locally then builds out your chosen custom Product Locator on a staging site and deliver you final stylized codes ready to launch.

Or, if you wish to control the design on your end, our Product Locator code "writes" raw HTML to your page, so you can grab the basic embed code and then use CSS to style it however you wish.

Link to this answer

How are dealer results determined?

Default dealer results settings

Locally's Product Locator will snap any stock match to the top of results within 45 miles from the shopper. When there are multiple stock matches near that shopper, they will be ranked based on proximity. Following stock matches, the Product Locator defaults to showing other nearby authorized dealers that either don't stock that item or don't provide an inventory feed to Locally, to allow a shopper to contact that store directly.

See the Dealer Locator custom options section for information on biasing stores of a certain category to always appear at the top of results, such as brand-owned stores, key accounts, etc.

Locally offers three ways to constrain the dealer results that display for specific products.

Option 1: Use categories to specify which dealers to display

You can use categories on your dealer list to restrict the results to only show dealers with a given category. To do so, simple add the line &category=XXX to your embed code's 'src' attribute. Results will be restricted to only show dealers that have been tagged with that category on your dealer list.

For example, if you have line of products that are only sold in bike shops, you can ensure that the dealer results for those Product Locators are only bike shops by adding a "bike" category tag to those dealers on your dealer list, and adding the line &category=bike to your embed code for those products.

Option 2: Tie dealer results to specific taxonomy nodes

Looking for something even more granular? We also can tie dealer results to specific taxonomy nodes. This is more involved, but allows a brand with multiple product and dealer types to give a highly accurate portrayal of dealers nearby who are likely to stock that product.

Option 3: Only display dealers who have the item in stock

Utilizing this option means Locally's Product Locator will only show stock matches for your products. Other nearby dealers who either don't stock that particular item or don't provide an inventory feed will never appear in Product Locator results.

This setting is typically used with our "Hide entire product locator when item not in stock" setting, which makes the Product Locator disappear from your PDP completely if a shopper is looking at a product in an area where Locally has no nearby dealers showing as in-stock for this product.

Link to this answer

How do we handle variants (sizes, colors, etc) on our product pages?

There are three ways to utilize the Locally Product Locator when your product page (PDP) displays and/or allows your site visitors to dynamically switch between sizes and colors.

Before getting started with any approach, go ahead and embed the Product Locator following these instructions in your testing environment. Make sure to use the &style=XXXX method described. This will ensure that the in-stock data for this product is being loaded at the 'style level'. The Product Locator will attempt to find nearby dealers with any of the variants of this style in stock.

Option 1: Do nothing when the user switches variants

This option is perfectly reasonable to use and is how most of our Product Locators are installed. The Product Locator will simply show all of the nearby stores where the product can be purchased, regardless of which variant has been chosen on your PDP. Our modal shows all available variants (sizes/colors) within that style-level grouping that are in-stock nearby that shopper.

Option 2: Reload the Product Locator using Javascript when the user switches variants

Our Product Locator can respond to a variant selection on your PDP to locate that specific variant in a nearby store. Call the following function to reload the Product Locator:

lcly_reload_0({ 'upc' : XXXX }); 

Replace the XXXX above with a single, or multiple UPCs, separated by commas. This method name may be called lcly_reload_1 or lcly_reload_2 depending on the id parameter you used when loading the Product Locator (0 is the default).

Option 3: Load multiple Product Locators on a single page

First, follow this guide to ensure that multiple product locators are installed correctly.

When the PDP loads, simply hide all of the Product Locators except for one. When the user switches variants, hide the visible Product Locator and show the applicable one using your own Javascript methods.

Note: this option only works well when all of your variants are sizes or all of your variants are colors. We do not recommend using this option if you have mixed variant types.

Link to this answer

Can we install multiple Product Locators or Locally widgets on one page?

Yes. First, make sure that you are including an id parameter in each embed code and that the id is different for each Product Locator. The id can be anything you want (a number is preferred) but it must be different for each Product Locator being loaded on the page.

Next, you must alter the id value in ALL parts of the embed code to match the id parameter.

For example, these two embed codes will work on the same page:

<!-- LOCALLY.COM WIDGET EMBED CODE -->
<div id="lcly-button-0">
  <a id="lcly-link-0" href="https://brands.locally.com" target="_blank">
    Product Locator by Locally
  </a>
</div>
<script id="lcly-script-0" async></script>
<script id="lcly-config-0">
  var lcly_config_0 = {
    "id": "0",
    "company_name": "Acme Outfitters",
    "company_id": "999"
  };
  var lcly_query_0 = Object.keys(lcly_config_0)
  .reduce(function(a,k){a.push(encodeURIComponent(k) + '=' 
  + encodeURIComponent(lcly_config_0[k]));return a},[]).join('&');
  var lcly_endpoint_0 = 'https://acme.locally.com/stores/map.js?' + lcly_query_0;
  document.getElementById('lcly-script-0').src = lcly_endpoint_0;
</script>

and

<!-- LOCALLY.COM WIDGET EMBED CODE -->
<div id="lcly-button-1">
  <a id="lcly-link-1" href="https://brands.locally.com" target="_blank">
    Product Locator by Locally
  </a>
</div>
<script id="lcly-script-1" async></script>
<script id="lcly-config-1">
  var lcly_config_1 = {
    "id": "1",
    "company_name": "Acme Outfitters",
    "company_id": "999"
  };
  var lcly_query_1 = Object.keys(lcly_config_1)
  .reduce(function(a,k){a.push(encodeURIComponent(k) + '=' 
  + encodeURIComponent(lcly_config_0[k]));return a},[]).join('&');
  var lcly_endpoint_1 = 'https://acme.locally.com/stores/map.js?' + lcly_query_1;
  document.getElementById('lcly-script-1').src = lcly_endpoint_1;
</script>

Notice how ALL instances of the id 0 have been replaced with 1.

Link to this answer

Can we access Product Locator data programmatically?

Yes. Brands will often want to be able to customize the user experience on their product detail pages based on the status of the Product Locator. The Product Locator will broadcast "events" containing information about it's current status to the HTML page in which it is embedded. In order to "listen" for these events, just add an event listener to the page:

window.addEventListener("LOCALLY_data_update", function(event) {
    // event.detail will contain an object will all location-related details
    // act upon event.detail here ...
}, false);

A sample event.detail output:

{
    id: 0, // the ID of the Product Locator instance
    n_items_with_stock: 3
}

Link to this answer

Can we track our own customers through Buy it Locally

Yes, if your website is already maintaining and tracking customer sessions, simply add the following parameter to your Product Locator embed code:

customer_id: 'abc123' // where this is your own internal ID or token for the customer

When this customer creates a Buy It Locally cart, your own ID will be saved and will become accessible via the carts endpoint in the Locally API.

Link to this answer

Can we make the Product Locator update elements on our page?

Yes. We have a feature called "Locally Markup". This makes it easy for you to have elements on your product page reflect the data that is being shown in the Product Locator. For example, if you add a class name to an element on your page, like this:

Find our products in <span class="lcly-city-name">your city</span>!

When the Product Locator loads it will overwrite the contents of that element. The final result would make your element render like this:

Find our products in <span class="lcly-city-name">Austin, TX</span>!

This can be a useful way to create a custom header or trigger for the Locally Product Locator display.

Link to this answer

How do I Install the Product Locator on BigCommerce

If you have a BigCommerce site, the best way to install the Product Locator is to add it directly to one of your "theme files". Before you can do that, you must have the ability to edit theme files. Theme files can only be edited in custom themes. If you have a stock theme (a theme purchased or installed directly into your BigCommerce account) then you must copy this theme to your own custom theme first. More information from BigCommerce support on copying themes in order to edit theme files.

If you are able to edit theme files, please navigate to Storefront Design > My Themes > Current Theme > Advanced > Edit Theme Files. The "Stencil File Editor" will open. Use the file/folder tree on the left to navigate to Templates > Components > Products > product-view.html. This file name may be different depending on your theme. You want to look for the file which contains the "Add to Cart" button because we want you to install the Product Locator after that button. Of course, please install the Product Locator wherever you wish! This is just a suggestion.

Once you are in the theme file editor, please install the Product Locator like so:

{{#if product.sku}}
    <!-- LOCALLY.COM WIDGET EMBED CODE -->
    <div id="lcly-button-0">
      <a id="lcly-link-0" href="https://brands.locally.com" target="_blank"></a>
    </div>
    <script id="lcly-script-0" async></script>
    <script id="lcly-config-0">
      var lcly_config_0 = {
        "company_name": "ACME Widgets",
        "button_text": "Buy it Locally",
        "button_id": "HTML",
        "company_id": "99999",
        "css": "3",
        "color_0": "#C50001",
        "style": "{{ product.sku }}",
        "n_related_styles": "3",
        "show_location_switcher": "1",
        "show_location_prompt": "1",
        "n_dealers": "3",
        "no_link": "1",
        "id": "0"
      };
      var lcly_query_0 = Object.keys(lcly_config_0)
      .reduce(function(a,k){a.push(encodeURIComponent(k) + '=' 
      + encodeURIComponent(lcly_config_0[k]));return a},[]).join('&');
      var lcly_endpoint_0 = 'https://haba.locally.com/stores/map.js?' + lcly_query_0;
      document.getElementById('lcly-script-0').src = lcly_endpoint_0;
    </script>
{{/if}}

Your settings many vary! But, notice {{ product.sku }} in the middle. That is the most important part. This utilizes the SKU that you have set in your BigCommerce product catalog. This snippet ensure that if you have a product SKU set for this product, BigCommerce will render the Locally Product Locator and injects the SKU into the Locally embed code. As long as your SKU matches the Locally Style Number that we have in our own product catalog, the Product Locator will work as expected.

Link to this answer

Used By Trusted Brands Worldwide

Learn how industry leaders use Locally to further their brand recognition.