Location Trigger
This template allows you to trigger content based on the player’s geographic location. The location feature polls the location of the player’s phone, and fires an event when the player is within a given radius of the geographic coordinates.
NOTE: Location Trigger runs on custom API for Spectacles 2021. It will not run on your phone or in Lens Studio.
Project Download
Please download the project here.
Use Cases
Location Trigger is a new, experimental feature, and we are actively exploring new use cases. Some ideas include:
- Travel Guide: trigger content when a player arrives at a location
- Live Action Roleplay
- Scavenger Hunt
- Detective Story
Location Trigger API
Compatibility
Make sure you have updated to the latest version of the Snapchat App on your phone, the Spectacles firmware, and Lens Studio.
- Snapchat v11.51.x and above
- Spectacles v4.67.x and above
- Lens Studio v4.4.1 and above
Enable Experimental API in Lens Studio
The experimental features in this API require that you update to Lens Studio 4.4.1 or later. In your Lens Studio project, you must enable experimental features:
- Open Lens Studio -> Preferences and check “Allow Experimental API.” Now the “Allow Experimental API” option will show in Project Info.
- Open File -> Project Info and check “Allow Experimental API.”
Location Radial Event
Description
This event is triggered when the player enters or exits the radius of the set location. It also fires directly after you bind the function to give you the current status.
Inherited Properties
event.latitude : Float
The float latitude of the location
event.longitude : Float
The float longitude of the location
event.radius : Float
The float radius in meters of the location
event.inRadius : Boolean
Determines whether or not user is in the radial boundary of the location
Location Region Event
Description
This event is triggered when the player enters or exits the geofence of the set location. It also fires directly after you bind the function to give you the current status.
event.geofence : Array Float
The array of float longitude and latitude which represents the boundaries of a location
event.inRegion : Boolean
Determines whether or not user is in the geofence boundary of the location
Handling Location Events
Location Radial Event is handled by placing the code in a script, and attaching the script to a scene object in your scene.
Create a new LocationRadialEvent and set latitude, longitude, and radius as follows:
var triggerEvent = script.createEvent("LocationRadialEvent");
triggerEvent.latitude = 34.023944;
triggerEvent.longitude = -118.394052;
triggerEvent.radius = 5;
Bind it to a function to receive an event every time you enter or exit the radius. This will also be called right after you bind the function to let you know the current state.
triggerEvent.bind(onLocationUpdate);
Trigger the event based on your location by choosing geographic coordinates local to you and setting them to the latitude and longitude of the event.
Sample Code
function onLocationUpdate(event) {
if (event.inRadius) {
script.status.text = "Inside the location";
} else {
script.status.text = "Outside the location";
}
}
try {
var triggerEvent = script.createEvent("LocationRadialEvent");
triggerEvent.latitude = 34.023944;
triggerEvent.longitude = -118.394052;
triggerEvent.radius = 5;
triggerEvent.bind(onLocationUpdate);
} catch (error) {
script.status.text = "Location API\nnot available";
}
function onLocationUpdate(event) {
if (event.inRegion) {
script.status.text = "Inside the location"
} else {
script.status.text = "Outside the location"
}
}
try {
var triggerEvent = script.createEvent("LocationRegionEvent")
triggerEvent.geofence = [-118.3941595,34.0240303,
-118.3939932,34.0238413,
-118.3939368,34.0238902,
-118.3941219,34.0240859,
-118.3941595,34.0240303]
triggerEvent.bind(onLocationUpdate)
} catch (error) {
script.status.text = "Location API\nnot available"
}
Choosing Geographic Coordinates
Geographic coordinates on a phone are only accurate within a 5 meter radius. Therefore, consider coordinates that give your player 5 meters on any side to walk around and trigger your content. Here are some best practices for geo coordinates to work more accurately on your player’s phone:
- Choose a coordinate that is outside
- Make sure the coordinate is under the sky, not under a tree
You can record latitude, longitude, and radius of your location in a few ways.
Best Way
Use this tool to retrieve the latitude, longitude and radius of your location. This website allows you to save your measurement to a simple link:
https://www.mapdevelopers.com/draw-circle-tool.php
Here is the example we used for Doggie Detective.
Second Way
Remotely on your computer:
- Open google maps
- Click the location
- Copy and paste the geographic coordinates into your Lens Studio Project
- Estimate the radius
Third Way
In person on your phone (less accurate):
- Open google maps
- Go to settings -> google maps -> location
- Toggle on “while using app” or “always”
- Toggle on “precise location”
- In google maps, hold the location until a pin pops up
- Click the pin
- Copy and paste the geographic coordinates into your Lens Studio Project
- Estimate the radius
Previewing Your Lens
You’re now ready to preview your lens on Spectacles 2021. To pair your lens with your Spectacles 2021, follow the Preview Your Lens On Device section on the Creating Lenses guide.
Each time you want to use location in your lens, you have to enable Location on your Spectacles 2021. This feature will only last for one hour.
- Update Snapchat on your phone
- Go to Spectacles Home in Snapchat.
- Tap “Experimental Features”
- Enable “Background Location”
Tip: For an implementation of how to notify your player in lens to enable this experimental feature, please visit the onLensStarted() function of the LensController script in the Doggie Detective project.