Shopper Geolocation
Geolocation plays a crucial role in providing personalized experiences based on shopper location. Use this guide to integrate Shopper Context API geolocation features with your storefront for enhanced shopper experiences.
With B2C Commerce version 24.7, you can work with geolocation information in the following ways:
- Look up a shopper's location using the client's IP address.
- Look up a shopper's location using the client's IP address and use that information to set context for subsequent requests.
- Manually provide a location and use that information in subsequent requests.
- When you use SCAPI to retrieve geolocation information, the client's IP address is used to retrieve geolocation information from the B2C Commerce platform, and the IP lookup is based on your database information. For details, see Geolocation Lookup for IP Addresses.
- An association with a location impacts future requests. For example, you have a dynamic customer group for which membership includes
request.geolocation.city == 'San Francisco'
. For the purposes of group membership evaluation, this geolocation location applies to subsequent requests for this shopper. For details, see Customer Segmentation Via Geolocation.
- Log in to Business Manager.
- Go to Administration > Global Preferences > Feature Switches.
- Check Enable Shopper Context.
Using SCAPI, geolocation information is retrieved using the client's IP address to look up geolocation information in the B2C Commerce platform.
Include the clientIp
attribute with a Shopper Context PATCH or PUT request, for example:
The following keys are provided in the HTTP response header x-geolocation
, and are delimited with semicolons (;):
- CountryCode
- Country
- City
- PostalCode
- MetroCode
- Region
- RegionCode
- Latitude
- Longitude
Consume the geolocation HTTP response header in a case insensitive way, because it can be returned as x-geolocation
or X-Geolocation
.
Retrieving geolocation with clientIp
returns information, but does not impact subsequent requests. To use the location provided by clientIp
on subsequent requests, you must specify the evaluateContextWithClientIp
query parameter:
If evaluateContextWithClientIp
is set to true:
- the
clientIP
is saved and is used with subsequent requests.
If evaluateContextWithClientIp
is set to false
:
- the clientIP is not saved and is not used with subsequent requests.
In both cases, the x-geolocation
response header is returned. Null or empty values are not returned.
You can also use the geoLocation
attribute to set a specific context geolocation. You can collect a user’s location via native browser functionality (navigator.geolocation) or via manual user input, and send these coordinates to the Shopper Context API for site personalization.
You can manually set any combination of the following optional parameters:
- countryCode
- country
- city
- postalCode
- metroCode
- region
- regionCode
- latitude
- longitude
The following Shopper Context example request provides the city
and countryCode
parameters in the geoLocation
attribute to set the geolocation information:
THe x-geolocation
response header returned is:
If you set a location using the geoLocation
attribute in the request body, it is saved as context for subsequent requests. If both geoLocation
and clientIp
are set in the context, the location set with geoLocation
takes precedence over the location resolved from the clientIp
.
For example, let's assume the following promotion configuration:
- For New York, USA: 20% discount on women's tops.
- For Boston, USA: 15% discount on women's tops.
In the following Shopper Context request, both clientIp
and geoLocation
attributes are provided. In this case, the geoLocation
value takes precedence and the response header x-geolocation
returns the location based on the geoLocation
attribute in the request:
The following x-geolocation
response header is returned:
Suppose the clientIp
12.12.12.1 resolves to New York, USA, but because the geoLocation
in the payload specifies Boston, US, the context is evaluated based on Boston-specific promotions, resulting in a 15% discount on women's tops.
In this case, you provide a prompt for the user to enter geolocation information, which you can then send to the Shopper Context API, for example:
When the geoLocation
attribute is updated in Shopper Context PATCH calls, the entire existing geolocation value is replaced, not individual property values. To make a change to the geolocation, you must send all required properties, because geolocation properties work together.
You can set a new location context using the geoLocation
attribute in the request body. The geoLocation
attribute contains:
countryCode
country
city
postalCode
metroCode
region
regionCode
latitude
longitude
Null values are not returned.
From a Script API perspective, dw.system.Request.getGeoLocation` returns the following geolocation information, which is useful when using hooks:
- City:
request.geolocation.city
- Country Name:
request.geolocation.countryName
- Country Code:
request.geolocation.countryCode
- Latitude:
request.geolocation.latitude
- Longitude:
request.geolocation.longitude
- Metro Code:
request.geolocation.metroCode
- Postal Code:
request.geolocation.postalCode
- Region Name:
request.geolocation.regionName
- Region Code:
request.geolocation.regionCode