This app is no longer maintained by VTEX. This means support and maintenance are no longer provided.

This app attempts to determine the user's location if it is not already known, first by requesting permission to use their browser's geolocation feature, then by looking up their location using their IP address as a fallback. The location is stored in the shippingData section of the orderForm and can then be used by other apps, such as Location Availability.

A block is also provided, which renders a form allowing the user to manually change their location.

Shopper Location also supports redirecting a user to a URL based on their location, determined by the app. See the Client Redirect section.

This app also supports white-label sellers' selection, allowing shoppers to choose one or more sellers available in their location. Shoppers will then be able to search and view products from those select sellers. See the Region Seller Selection section.

The Google Geolocation API key in your Inventory & Shipping settings is required for the geolocation feature.

To use the IP lookup fallback, you must have an API key for https://ip-geolocation.whoisxmlapi.com.

1. Using VTEX IO CLI, install vtex.shopper-location in the desired account.

2. In your account's admin dashboard, go to Apps > My Apps and click the Settings button for Shopper Location.

3. Enter your API key for https://ip-geolocation.whoisxmlapi.com in the provided field and click Save. If you plan to use the Client Redirect feature, it's configured here as well.

4. Modify your store-theme as follows:

• Add the following as dependencies in your theme's manifest.json file, if not already present:

• In one of the JSON files in your theme's store folder, define the shopper-location block and its children, adjusting the props as needed:

• Also, in one of the JSON files, place the shopper-location block in your layout. For example, to place the block in the header:

You can redirect the user to a country-specific URL based on their location. In the App Settings, enter the alpha-3 country code and URL for each supported country.

On their first visit, if a user is not on their country's website, a modal will display an option to redirect to their country's website. For users in a country without an entry in the App Settings, no option is displayed.

Additionally, there is an Automatic Redirect option that redirects the user without displaying the modal.

Allow users to select one or more sellers serving their location from a list, and display only products carried by those sellers in search results.

️ For this feature to work properly, the item cannot have inventory in seller "1". If there's stock in seller "1", the item will always appear in the search results, regardless of the inventory in the sellers selected.

Add the region-sellers block as a child of the shopper-location block to get started:

Props

shopper-location:

Prop name	Type	Description	Default value	Accepted values
autofill	array	Define which address fields should be filled	undefined	Array with any of these values ["city", "country", "neighborhood", "number", "postalCode", "state", "street"]

change-location:

Prop name	Type	Description	Default value	Accepted values
postalCode	string	Define the postalCode position on the form	last	first,last
autocomplete	boolean	Enables Google autocomplete based on the postalCode (Only works when postalCode is set to first)	false	true,false
notRequired	array	Turn visible fields not required	undefined	["city", "country", "neighborhood", "number", "state", "street", "complement","receiverName", "reference"]
hideFields	array	Hide fields and turn them not required	undefined	["city", "country", "neighborhood", "number", "state", "street", "complement","receiverName", "reference"]

region-sellers:

Prop name	Type	Description	Default value	Accepted values
mode	string	Specify if component will be used as a search filter (filter). Otherwise display as a dropdown (default).	default	filter, default
initiallyCollapsed	boolean	When using filter mode, set sellers list to display as collapsed (true) or open (false) initially.	false	true,false
displayStoreIcon	boolean	Display store icon.	true	true,false
useApplyButton	boolean	Apply sellers' selection using a button (true) or automatically apply changes after each selection (false).	false	true,false

To apply CSS customizations to this and other blocks, follow the instructions in Using CSS Handles for store customization.

CSS Handles
changeLocationAddressContainer
changeLocationContainer
changeLocationFormContainer
changeLocationGeoContainer
changeLocationMapContainer
changeLocationGeoErrorContainer
changeLocationGeolocationButton
changeLocationSubmitContainer
changeLocationSubmitButton
changeLocationTitle
changeLocationError
sellersSelector
sellersSelectorContainer
storeListWrapper
storeIcon
storesCurrent
storesCurrentNames
storeFilterTitle
storeListIcon
storeListContainer
storeListItems
storeListItem