Using the VPS Coverage API

The VPS Coverage API is used to discover VPS coverage areas and understand how best to localize with VPS localization targets.

You can use the VPS Coverage API to find VPS coverage areas around a given geographic location. The ARDK backend will provide a list of geographic coverage areas where a user can use VPS to localize. A coverage area may contain a set of VPS localization targets powered by VPS-activated Wayspots, which help the user localize within the area. You can use the VPS Coverage API to get details about localization targets, including the target name, target latitude and longitude, and a “hint image” photo of the target.

Use the VPS Coverage API when you need to guide your users to nearby VPS coverage areas, or help your users find and localize VPS targets within a particular area. Helping your users find VPS localization targets will make the actual VPS localization process much smoother for the user. You’d typically want to use this API to guide users to an VPS coverage area and show them what to point their AR-enabled device at before starting VPS localization.

Note

VPS Coverage API only returns information about publicly-accessible VPS coverage areas and localization targets. Currently, a VPS localization target is associated with a VPS-activated Wayspot. VPS Coverage API can’t be used to get information about Private VPS Locations.

Typical User Flow When Using the VPS Coverage API

Before your users can localize with VPS, they need to know information such as where a valid VPS coverage area is, how far they are from the location, and what they should be focusing on with their AR-enabled device when they localize. You can use the following flow to provide this information:

First, determine what VPS coverage areas are available to the player. The VPS Coverage API can provide a list of coverage areas near a specific geographic location and zero or more localization targets within a coverage area. You can display coverage areas and targets (typically in a map-based UI element) to help your users inspect and choose areas and targets that they can visit. Users can also use coverage area information to determine how close they are to the coverage area where they can start to localize.

The following example screenshot shows a map-based UI that lets the user view coverage areas and localization targets and select a target on the map.

../../_images/vps_coverage_voyage_ca_example.png

Next, as your user inspects or chooses particular localization targets, you can make VPS Coverage API calls to get detailed information about the selected targets. Target details, such as the name, GPS location, and “hint image” photo of the target, can be displayed to the user to help them understand what localization targets they’re looking for. You can also use a 3rd party map API to calculate directions for the user on how to get to a selected target location.

The following screenshot shows a map-based UI where a user has selected a specific localization target, and the hint image of the selected target is shown below the map.

../../_images/vps_coverage_voyage_lt_example.png

Finally, once the user has selected a localization target and moved within the coverage area for the target, you can instruct them on how to begin the VPS localization process, as described in Localizing with VPS.

Note

Use of features such as the VPS Coverage API involves the collection of personal information from your end user. For more information, see the Lightship ARDK Data Privacy FAQ.

Enable Location Permissions

Because the VPS Coverage API uses device location information, you’ll need to make sure the user has enabled location permissions on their device. See Permissions for details on requesting device permissions.

Discover VPS Coverage Areas and Localization Targets

You can use the VPS Coverage API to find VPS coverage areas near a specific geographic location. This location can be based on the current user or device location, or you can specify a latitude & longitude. You may need to provide a specific location if your app uses a map UI and you want to display locations relative to the center of the map as the user pans the map.

To use the VPS Coverage API to find locations near the current device location, you’ll need to do the following:

Create an ILocationService instance and subscribe to the OnLocationUpdated event to get updates for the current device location. If you’re running in the Unity editor, you can use SpoofLocationService to set a spoofed location.

Note

If you want to use a specific location rather than the device location, you don’t need to use a ILocationService.

using Niantic.ARDK.LocationService;

private ILocationService _locationService;

// Default is the Ferry Building in San Francisco
private LatLng _spoofLocation = new LatLng(37.79531921750984, -122.39360429639748);

// Start is called before the first frame update
void Awake()
{

    // ...

    _locationService = LocationServiceFactory.Create();

#if UNITY_EDITOR
    var spoofService = (SpoofLocationService) _locationService;

    // In editor, the specified spoof location will be used.
    spoofService.SetLocation(_spoofLocation);
#endif

    _locationService.LocationUpdated += OnLocationUpdated;
    _locationService.Start();
}

Create an ICoverageClient instance used to make VPS Coverage API requests.

using Niantic.ARDK;
using Niantic.ARDK.VPSCoverage;
using Niantic.ARDK.VirtualStudio.VpsCoverage;

private RuntimeEnvironment _coverageClientRuntime = RuntimeEnvironment.Default;
private ICoverageClient _coverageClient;
private VpsCoverageResponses _mockResponses;

void Awake()
{

    // ...

    // The mockResponses object is a ScriptableObject containing the data that a Mock
    // implementation of the ICoverageClient will return. This is a required argument for using
    // the mock client on a mobile device. It is optional in the Unity Editor; the mock client
    // will simply use the data provided in the ARDK/VirtualStudio/VpsCoverage/VPS Coverage Responses.asset file.
    _coverageClient = CoverageClientFactory.Create(_coverageClientRuntime, _mockResponses);

    // ...
}

In your OnLocationUpdated event handler, use ICoverageClient.RequestCoverageAreas() with the new location info to request nearby locations. In your request you need to provide:

The desired location latitude and longitude
A request radius in meters (up to 2000 meters). VPS Coverage API will return VPS coverage areas that are within this radius of the request location.

You’ll also provide a callback to RequestCoverageAreas() that will be called when the response is received. If you prefer to use the Task-based async await pattern, you can use RequestCoverageAreasAsync(). Both RequestCoverageAreas() and RequestCoverageAreasAsync() are non-blocking calls.

void OnLocationUpdated(LocationUpdatedArgs args)
{
    _locationService.LocationUpdated -= OnLocationUpdated;
    _coverageClient.RequestCoverageAreas(args.LocationInfo, _queryRadius, ProcessAreasResult);
}

Process the response.

async void ProcessAreasResult(CoverageAreasResult result)
{
    // ...

    if (result.Status != ResponseStatus.Success)
        return;
    foreach (var area in result.Areas)
    {
        // Process coverage areas accordingly
    }
}

If the request is successful, the response will contain a list of CoverageAreas near the request location, within the request radius. Each CoverageArea contains:

Zero or more localization target IDs
A coverage area shape. The shape is a simple (no holes) polygon defined by an array of latitude and longitude points in clockwise order.
A localizability quality value, which gives an estimate of how easy it will be for users to localize in that area. A coverage area with a LocalizabilityQuality of PRODUCTION means that users should be able to localize in that area under a wide range of conditions. A coverage area with a LocalizabilityQuality of EXPERIMENTAL means user localizations in that area might not work under all conditions.

Note that:

A coverage region is currently constrained to roughly a 5 meter radius around a localization target. This radius may increase in the future.
If the user has not allowed location permissions, or the device has location permissions disabled, the request will fail. A LocationService.StatusUpdated event will be invoked with the specific error (user permission not granted, or system/device level location disabled)

See the VpsCoverageExample and VpsCoverageListExample samples in the ARDK-Examples package for more examples of getting coverage areas.

Get VPS Localization Target Details

Once you’ve obtained a list of localization target IDs, use RequestLocalizationTargets() or RequestLocalizationTargetsAsync() to get detailed information about each target. You’ll need an ICoverageClient instance to make the request, as described in the previous section.

Provide an array of target IDs you want detailed information about. The list of CoverageAreas returned from a RequestCoverageAreas() request contains target IDs within the given coverage areas. The following example extracts the list of target IDs from the list of CoverageAreas and passes this to a call to RequestLocalizationTargets().

async void ProcessAreasResult(CoverageAreasResult result)
{
    var allTargets = new List<string>();
    if (result.Status != ResponseStatus.Success)
        return;
    foreach (var area in result.Areas)
    {
        allTargets.AddRange(area.LocalizationTargetIdentifiers);
    }

    _coverageClient.RequestLocalizationTargets(allTargets.ToArray(), ProcessTargetsResult);
}

If the request is successful, you’ll get target details in a dictionary of LocalizationTargets that you can process.

async void ProcessTargetsResult(LocalizationTargetsResult result)
{
    if (result.Status != ResponseStatus.Success)
        return;
    if (result.ActivationTargets.Count > 0)
    {
        Vector2 imageSize = TargetImage.rectTransform.sizeDelta;
        LocalizationTarget firstTarget = result.ActivationTargets.FirstOrDefault().Value;
        firstTarget.DownloadImage((int)imageSize.x, (int)imageSize.y, args => _targetImage.texture = args);
        // retrieve other LocalizationTarget details and display to user as needed
    }
}

Each LocalizationTarget contains the target ID, a target name, the latitude/longitude of the target, and a “hint image” URL that points to an image of the target. LocalizationTarget also provides DownloadImage() and DownloadImageAsync() convenience methods to download the hint image to a texture. Use the hint image to show your users a picture of what they need to point their device camera at when they need to do VPS localization.

Here’s an example screenshot showing a list of retrieved target details, including hint images:

../../_images/vps_coverage_loc_target_list.png

See the VpsCoverageExample and VpsCoverageListExample samples in the ARDK-Examples package for more examples of RequestLocalizationTargets() requests and how to process the results.

Displaying Locations to the User

How you display coverage area and localization target information to your users will depend on your use case and application design, however one common method is using a map UI element.

You’ll need to use 3rd party tools for this, such as a webview Unity plugin and a 3rd party map service API. Exact steps for all 3rd party tools are beyond the scope of this documentation, but the high-level steps are:

Register with a map service API such as Mapbox or Google Maps.
Add a webview Unity plugin to your project, such as Vupelx or gree.
Add your Map UI HTML, JavaScript, and CSS code to your project. For a simple Mapbox example, see https://docs.mapbox.com/mapbox-gl-js/example/simple-map/
Configure your Unity scene script to load your webview with your HTML, JavaScript, and CSS assets. For example, if you started with the gree sample app, you might need to update SampleWebView.cs to load your streaming assets rather than the sample assets.
Make sure to add in your map service provider API key where needed (either in your web asset code or script code)
Add JavaScript code to visualize coverage areas and localization targets on the map. If you’re using MapBox, here’s an example JavaScript function to add coverage areas to the map:

function addAreaToMap(data)
{
   const firstVertex = data.features[0].geometry.coordinates[0][0][0] + ',' + data.features[0].geometry.coordinates[0][0][1];

   const areaName = 'area' + firstVertex;
   const outlineName = 'outline' + firstVertex;

   map.addSource(areaName, {
       'type': 'geojson',
       'data': data
   });

   // Add a new layer to visualize the polygon.
   map.addLayer({
       'id': areaName,
       'type': 'fill',
       'source': areaName, // reference the data source
       'layout': {},
       'paint': {
           'fill-color': '#0080ff', // blue color fill
           'fill-opacity': 0.5
       }
   });
   // Add a black outline around the polygon.
   map.addLayer({
       'id': outlineName,
       'type': 'line',
       'source': areaName,
       'layout': {},
       'paint': {
           'line-color': '#000',
           'line-width': 3
       }
   });
}

Here’s an example of adding localization targets to the map:

function addTargetsToMap(data)
{
    const targetName =  data.features[0].geometry.properties.location_target_identifier;

    map.addSource(targetName, {
        'type': 'geojson',
        'data': data
        });

    // Add a circle layer
    map.addLayer({
        'id': targetName,
        'type': 'circle',
        'source': targetName,
        'paint': {
        'circle-color': '#4264fb',
        'circle-radius': 8,
        'circle-stroke-width': 2,
        'circle-stroke-color': '#ffffff'
        }
    });
}

See also the Mapbox samples for updating the map, such as Add Polygon to Map and Adding a default marker.

Configure your project to be able to invoke JavaScript from your Unity script code. The webview framework you’re using should provide a C# interface to evaluate JavaScript on the webview object. If you’re using gree, see the following example: https://github.com/gree/unity-webview/issues/795
When you get coverage area and location info from VPS Coverage API, pass the information to your JavaScript code to update the map accordingly. Convenience methods are provided to convert coverage area and target information to GeoJSON. For example, to provide the info to the MapBox JavaScript examples shown in Step 6, you’d use something like the following in your Unity script code:

void AddAreasToMap()
{
    foreach (var area in _areas)
    webViewObject.EvaluateJS("addAreaToMap(" + area.ToGeoJson() + ");");
}

void AddTargetsToMap()
{
    foreach (var target in _targets)
    webViewObject.EvaluateJS(@"addTargetsToMap(" + target.Value.ToGeoJson() + ");");
}

Depending on your use case, you may also need to update the map to be centered on the user’s location, or draw directions from the user’s current location to a particular target or area.