If your site is moving, the NAO Suite will need some additional information to offer the same capabilities as for static sites, especially to be able to use the phone motion sensors.
Prerequisites
- NAO SDK fully integrated following the existing documentation and guidelines:
- A way to get the location information about your moving site (timestamp, location in latitude/longitude, and true heading) at the mobile application level. This information can usually be obtained through an API provided by your IT department.
Process
- Ask Pole Star to configure your site to accept moving site information from your app. If the reference heading of your site is not aligned on the North, provide that information to Pole Star.
- Implement the integration guidelines described in the next sections.
Integration guidelines
setExternalLocation API
Description
Android
void setExternalLocation(android.location.Location yourSiteLocation)
iOS
(void) setExternalLocation:(CLLocation *)yourSiteLocation
Call sequence
Put the location information (location in lat/long and heading) about your moving site in a Location (Android) or CLLocation (iOS) object, and call the setExternalLocation method on your locationHandle object that you should already have created in the initial integration phases.
Android
handle.setExternalLocation(locationObject)
iOS
[[locationHandle setExternalLocation] yourSiteLocation: /* your (id<CLLocation >) */];
This call should be performed:
- After having received an onEnterSite() (Android) or didEnterSite() (iOS) callback. This step is the most critical one, and works for mono-site as well as multi-sites API Keys.
- After each of these events:
- Significant change in heading (>+-5°);
- Significant change in latitude/longitude (>+-1 degree in latitude or longitude);
- Significant distance covered (>2km)
- No update for 2 minutes.
Behavior
Once the setExternalLocation API is called, the passed compass offset will be used until a new call to the setExternalLocation is made, or until the NAO SDK is either killed or destroyed.
NAO_COARSE_LOCATION NAOLocationHandle status
If you do not call the setExternalLocation API, the location engine will stop using the motion sensors of the phone, and the NAO_COARSE_LOCATION location status update will be sent to the application through the didLocationStatusChanged() and onLocationStatusChanged() callbacks, respectively for iOS and Android.
You can decide at the application level what to do with that information (show a message to the user, disable the location feature, do nothing, …)
Warnings
Your App has the responsibility to update the external location information whenever possible.
Location precision in a moving site depends of the location and motion data provided to setExternalLocation().
Be sure to call setExternalLocation() only after NAOLocationHandle’s method start() has been called and an enter site callback has been received.