logo

Module 3

GIVING HINTS IN CUSTOM LOCATION LENSES
Every Custom Location Lens is unique, and its accessibility and experience is tied to a physical location. That’s why we recommend creating and displaying hints to improve the overall Lens experience and encourage safe use of the Lens. In this module, we’ll cover five hints that can help Snapchatters successfully and safely enjoy your Lens.

Rear Camera Hint

Generally, Lenses using Custom Location AR are meant to be experienced with the Rear Camera. There are two ways to notify Snapchatters to use their rear camera:

Default method (Project Info)

You may want to set the official hint of your project to “Try this on the Rear Camera” in the Project Info when submitting the Lens.  
Please note that unchecking that the Lens is Made for Front Camera will hide the Lens from Snapchatters’ carousel unless they are already in Rear Camera mode.


Script

If you would rather present a custom hint within your Lens, you are able to create one with script. Try adding a callback to the CameraFrontEvent to tell Snapchatters to switch to the rear camera.

Safety Hint

Make sure to remind Snapchatters to stay aware of their surroundings when they load your lens. You can do so by creating a Hints Componentfrom your script that is set to "lens_hint_warning_please_be_aware_of_your_surroundings". 
myHintsComponent.showHint("lens_hint_warning_please_be_aware_of_your_surroundings", displayTime) 
A displayTime of -1 will keep the hint on screen until calling myHintsComponent.hideHint("lens_hint_warning_please_be_aware_of_your_surroundings")

Loading Message

Every Custom Location Lens needs to load the scanned CV data (See Module 2) before it can start the tracking process. A loading message can help Snapchatters understand the process. This is particularly helpful for Snapchatters who are experiencing slower data speeds.
Get a reference to the Device Location Tracking Component on your Camera and assign your own loading success and failure functions to the following properties:

DeviceLocationTrackingComponent.onLocationDataDownloaded = myLoadingSuccessFunction; DeviceLocationTrackingComponent.onLocationDataDownloadFailed = myLoadingFailedFunction;
Tip: To assign multiple functions to the Device Location Tracking Component callbacks, use something like the Wrap Function:

Location Hint

Your Lens should direct Snapchatters to your location. You can check if the Snapchatter is within acceptable range to successfully attempt tracking by checking DeviceLocationTrackingComponent.locationProximityStatus.If the result is LocationProximityStatus.OutOfRange, you should tell the Snapchatter where to go using one or more of the following methods:

By Name

You can explicitly tell where to go, preferably by name if your location has a recognizable name.

By Distance

Display how far the Snapchatter is from the location by referencing DeviceLocationTrackingComponent.distanceToLocation. Please note that this the accuracy of the number may fluctuate based on the strength of the Snapchatters’ GPS signal.

Tracking Setup Instructions

If the Snapchatter is close enough for Custom Location AR  to start recognizing the Snapchatter’s perspective, the tracking component will automatically start this process.
To help guide Snapchatters, provide instruction to point at the location from a recognizable perspective as soon as DeviceLocationTrackingComponent.locationProximityStatus is LocationProximityStatus.WithinRange. Then, you can hide the instruction by assigning a method to DeviceLocationTrackingComponent.locationFound or once DeviceLocationTrackingComponent.isTracking() is true.

Troubleshooting Tips

Many factors can get in the way of successful tracking. We recommend showing specific tips if the Snapchatter still isn’t tracking after a few seconds.
Once Custom Location AR tracking has started, the Snapchatter’s experience can begin. If your Lens has multiple phases for the Snapchatter to enjoy, use hints to guide them. For example, if a Snapchatter is taking longer than expected to complete a phase, a text can pop up to hint at what needs to be done. (i.e. “OPEN YOUR HAND” or “TAP STATUE”). Module 4 will focus on a specific type of interaction: Spatial Triggers.