1. Home
  2. Docs
  3. Unity SDK
  4. Programming API
  5. Location Trigger and Location Fence

Location Trigger and Location Fence

This article will cover how to trigger a callback when the user is in range (or out of range) of a location. There are two ways of accomplishing this: LocationTriggerPool and LocationFence.

Location Trigger Pool

LocationTriggerPool is a class used for creating a one-shot Location based trigger. You can assign multiple gps locations, a distance radius, and a callback. When the user is in range of any one of the locations, the assigned callback will be called. After the user is in range, the trigger pool will be deconstructed. This means the callback can only be triggered once.

    1. Create a LocationTriggerPool object. The values passed to the constructor are the default trigger ranges. You do not need multiple LocationTriggerPool objects to listen to multiple Location groups with different callbacks.
var m_triggerPool = new LocationTriggerPool(0, 75);
    1. Call start on your LocationTriggerPool object.
m_triggerPool.Start();
    1. Watch a Location.
m_triggerPool.WatchLocation(
    myLocationPoolID,
    myLocation,
    (inRangeLocations) =>{
        foreach(var loc in inRangeLocations)
        {
            Debug.Log("The Player is in range of " + loc.Name);
        }
    },
    new DoubleRange(20, 100)
);

This call sets up the trigger pool object to track a single location called myLocation. The location(s) passed to the trigger pool get assigned to the string id myLocationPoolID. This id can be passed to the StopWatching(id) call to stop the trigger pool object from listening for these location.

The third argument is the callback that gets called when the user is in range. The callback gets passed a list of all the locations that the user is in range of. The user may be in range of multiple locations at the same time.

The final argument is the range at which the user will trigger the callback. In the example above, the user must be within 100 metres from myLocation, but must also be at least 20 metres away from myLocation. This creates a “donut” around the location where the callback is triggered.

    1. Get in range.

Now these location(s) are ready to trigger the callback. Get in range any one of the locations to trigger the callback. When you have gotten in range of any one of the locations, the callback will be triggered. This will also cause the trigger to be torn down for all the locations. A LocationTriggerPool can only be triggered one time, then it is removed.

    1. Cleanup the pool.
m_triggerPool.StopWatching(myLocationPoolID);

If your location pool was never triggered, and you want to stop listening for the user at those locations, pass the location pool id to stop listening.

See LocationValuablesSpawnItemDriver.cs in the Ghost Hunter project for an example of this class being used.

Location Fence

LocationFence is a class that can be used for triggering callbacks based on a set of locations. Both an in-range and an out-of-range callback can be assigned. These callbacks can be triggered multiple times, and will only stop being called when the LocationFence is explicitly torn down.

    1. Create a LocationFence object. To use multiple Location groups with different callbacks assigned, you will need to create a LocationFence Object for each Location group. Use the class ForegroundPositionService to create your fence.
m_fence = ForegroundPositionService.Instance.CreateFence(
    location,
    minRange,
    maxRange,
    (locations) =>
    {
        Debug.Log(“The user is in range.”);
    },
    () =>
    {
        Debug.Log(“The user is out of range.”);
    }
);

Let’s take a closer look at the arguments passed to the CreateFence call.

      1. Location

This is the location (or locations) to trigger the callbacks.

      1. minRange

The distance away from the location(s) the user must be to trigger the in-range callback. Often set to 0.

      1. maxRange

The max distance the user can be away from the location(s) to trigger the in-range callback.

      1. Callback 1 (in range)

The callback to trigger when the user is in range. Optionally can be passed a list of locations that the user is in range of.

      1. Callback 2 (out of range)

The callback to trigger when the user is out of range of the locations.

    1. Discard your fence to stop listening.
ForegroundPositionService.Instance.DiscardFence(m_fence);

Unlike LocationTriggerPool, the LocationFence will continue triggering callbacks unless explicitly torn down. Make sure to call DiscardFence when you want to stop listening for the user’s position near these locations.

See SelectedLocationPanel.cs for an example of this class being used.

Was this article helpful to you? Yes No

How can we help?