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.

Lens Studio Support

[Spectacles 2021] Location Trigger Template