Documentation
Feedback
Guides
VTEX IO Apps

VTEX IO Apps
Shopper Location
Official extension
Version: 1.8.1
Latest version: 1.8.1

This app attempts to determine the user's location if not already known, first by requesting permission to use their browser's geolocation feature, then by looking up their location based on 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 off their location determined by the app. See the Client Redirect section.

This app also supports white label sellers selection, allowing shoppers to select 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.

:information_source: The Google Geolocation API key is required, and is configured in the account's Shipping settings (/admin/logistics/#/config)

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

Configuration

  1. 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 is also configured here.

  4. Modify your store-theme as follows:

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

_10
"vtex.store-components": "3.x",
_10
"vtex.modal-layout": "0.x"

  • Add Shopper location to your peer dependencies:

_10
"vtex.shopper-location": "1.x"

  • 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:

_45
"shopper-location": {
_45
"children": ["modal-trigger#address"]
_45
},
_45
"modal-trigger#address": {
_45
"children": ["user-address", "modal-layout#address"]
_45
},
_45
"user-address": {
_45
"props": {
_45
"variation": "bar",
_45
"showStreet": false,
_45
"showCityAndState": true,
_45
"showPostalCode": true,
_45
"showPrefix": false,
_45
"showIfEmpty": true
_45
}
_45
},
_45
"modal-layout#address": {
_45
"children": ["modal-header#address", "modal-content#address"]
_45
},
_45
"modal-header#address": {
_45
"children": ["flex-layout.col#address-header"]
_45
},
_45
"flex-layout.col#address-header": {
_45
"children": ["rich-text#address-header"],
_45
"props": {
_45
"paddingLeft": 5
_45
}
_45
},
_45
"rich-text#address-header": {
_45
"props": {
_45
"text": "### Change Location"
_45
}
_45
},
_45
"modal-content#address": {
_45
"children": ["change-location"]
_45
},
_45
"change-location": {
_45
"props":{
_45
"postalCode": "first",
_45
"autocomplete": true,
_45
"notRequired": ["street", "number", "city", "state"],
_45
"hideFields": ["complement", "neighborhood", "receiverName", "reference"],
_45
"autofill": ["city", "country", "neighborhood", "number", "postalCode", "state", "street"]
_45
}
_45
},

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

_20
"flex-layout.row#header-desktop": {
_20
"props": {
_20
"blockClass": "main-header",
_20
"horizontalAlign": "center",
_20
"verticalAlign": "center",
_20
"preventHorizontalStretch": true,
_20
"preventVerticalStretch": true,
_20
"fullWidth": true
_20
},
_20
"children": [
_20
"flex-layout.col#logo-desktop",
_20
"flex-layout.col#category-menu",
_20
"flex-layout.col#spacer",
_20
"shopper-location",
_20
"search-bar",
_20
"locale-switcher",
_20
"login",
_20
"minicart.v2"
_20
]
_20
},

Client Redirect

You have the option to redirect the user to a country specific URL, based on the user's 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 be redirected to their country specific website. For users located in a country that does not have an entry in the App Settings, no option is displayed.

Additionally, there is an Automatic Redirect option, that will redirect the user automatically, without displaying the modal.

Region Sellers Selection

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

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

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


_10
"shopper-location": {
_10
"children": ["modal-trigger#address", "region-sellers"]
_10
},

Props

change-location:

Prop nameTypeDescriptionDefault valueAccepted values
postalCodestringDefine the postalCode position on the formlastfirst,last
autocompletebooleanEnables google autocomplete based on the postalCode (Only works when postalCode is set to first)falsetrue,false
notRequiredarrayTurn visible fields not requiredundefined["city", "country", "neighborhood", "number", "state", "street", "complement","receiverName", "reference"]
hideFieldsarrayHide fields and turn them not requiredundefined["city", "country", "neighborhood", "number", "state", "street", "complement","receiverName", "reference"]
autofillarrayDefine which address fields should be filledundefinedArray with any of these values ["city", "country", "neighborhood", "number", "postalCode", "state", "street"]

region-sellers:

Prop nameTypeDescriptionDefault valueAccepted values
modestringSpecify if component will be used as a search filter (filter). Otherwise display as a dropdown (default).defaultfilter, default
initiallyCollapsedbooleanWhen using filter mode, set sellers list to display as collapsed (true) or open (false) initially.falsetrue,false
displayStoreIconbooleanDisplay store icon.truetrue,false
useApplyButtonbooleanApply sellers selection using a button (true) or automatically apply changes after each selection (false).falsetrue,false

Customization

In order to apply CSS customizations in this and other blocks, follow the instructions given in the recipe on 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
See also
VTEX App Store
VTEX IO Apps