amp-user-location
Description | Requests the user's location and provides it to AMP components. |
Availability | Experimental. The amp-user-location experiment must be enabled to use this component. |
Required Script | <script async custom-element="amp-user-location" src="https://cdn.ampproject.org/v0/amp-user-location-0.1.js"></script> |
Supported Layouts | nodisplay |
Behavior
The amp-user-location
component can be used in combination with other components to
send the user's location as part of other AMP components' requests. For example, to send the user's
location with a form or an analytics request, the Variable Substitution variables can be used.
Attributes
id (required)
The id
attribute is required and allows the component to be referenced in AMP Actions and Events.
src (optional)
The src
attribute specifies a remote configuration for the amp-user-location
component.
<amp-user-location id="location" src="https://www.example.com/amp-user-location.json" layout="nodisplay" ></amp-user-location>
Alternatively, a local configuration can be specified in a script
tag.
<amp-user-location id="location" layout="nodisplay"> <script type="application/json"> { "fallback": {"lat": 40, "lon": -40}, "maximumAge": 60000, "timeout": 5000 } </script> </amp-user-location>
AMP Actions
amp-user-location
exposes the request
action. This action is required to send the user's location
to another AMP component. This will cause the browser to prompt the user to approve location access
for the current domain, if the user has not already.
<button on="tap: location.request()">Use my location</button> <amp-user-location id="location" on="approve:…" layout="nodisplay"> </amp-user-location>
AMP Events
amp-user-location
exposes the following events
Event | Description |
---|---|
approve |
This event is fired when the user triggers the request action and then approves the browser prompt to access their location, or the user has previously approved the prompt. The event object contains lat , lon , and source properties. |
deny |
This event is fired when the user triggers the request action and then denies the browser prompt to access their location, or the user has previously denied the prompt. |
error |
This event is fired when the user triggers the request action and and error occurs. This can happen if the browser takes too long to retrieve the location information, if the hardware is unavailable, or other errors occur. |
Variable Substitution
The user's location is also available via AMP variable substitution:
AMP_USER_LOCATION
or ${ampUserLocation}
returns the latitude and longitude separated by a comma.
AMP_USER_LOCATION(LAT)
or ${ampUserLocation(LAT)}
returns the latitude.
AMP_USER_LOCATION(LON)
or ${ampUserLocation(LON)}
returns the longitude.
AMP_USER_LOCATION(SOURCE)
or ${ampUserLocation(SOURCE)}
returns the source. The source may be one of debug
, fallback
, geolocation
, unavailable
, or unsupported
.
The AMP_USER_LOCATION_POLL
or ${ampUserLocationPoll}
substitution is also available with the same
syntax as above. It will wait for the location to be requested before resolving, and will prevent a
request from occurring until that time. Polling is useful when the location is required for the request.
Validation
See amp-user-location rules in the AMP validator specification.
You've read this document a dozen times but it doesn't really cover all of your questions? Maybe other people felt the same: reach out to them on Stack Overflow.
Go to Stack Overflow Found a bug or missing a feature?The AMP project strongly encourages your participation and contributions! We hope you'll become an ongoing participant in our open source community but we also welcome one-off contributions for the issues you're particularly passionate about.
Go to GitHub