Location API

This page details all of the available NEON API functionality contained within the static API class Neon.

Requesting Permissions for NEON Location Service

Before you can begin tracking, the user needs to grant NEON Location Service two permissions: LOCATION and STORAGE. This allows NEON Location Service the ability to access the location of the device, and to access data stored on Android external storage.

NOTE: If you call Neon.bind() without obtaining these permissions, a security exception will be thrown.

Neon.startPermissionActivityForResult(visibleActivity, requestCode) should be called if Neon.hasRequiredPermissions(context) returns false. You should then handle the user accepting or rejecting those permissions by checking the result code returned to the supplied request code. If the result code is Activity.RESULT_OK, then the location service can be started. If Activity.RESULT_CANCELED, then the user has rejected the permissions and the location service cannot be started.

boolean hasRequiredPermissions(Context context)
boolean startPermissionActivityForResult(Activity visibleActivity, int requestCode)

The following code snippet gives an example of requesting and handling permissions:


public static final int PERMISSION_ACTIVITY_REQUEST_CODE = 1003;

void startLocationService() {

    if(!Neon.hasRequiredPermissions(mapsActivity.getApplicationContext()))
    {
        Log.i(LOG_TAG, "starting NEON permissions activity");
        Neon.startPermissionActivityForResult(mapsActivity, PERMISSION_ACTIVITY_REQUEST_CODE);
    }
    else
    {
        if (!Neon.isBound())
        {
            Log.i(LOG_TAG, "starting NEON Location Service");
            Neon.registerLocationUpdates(this);
            Neon.registerEvents(this);
            Neon.bind(mapsActivity.getApplicationContext());
        }
    }
}

@Override
protected void onActivityResult(int requestCode, int resultCode, Intent data) 
{
    switch (requestCode) 
    {
        case PERMISSION_ACTIVITY_REQUEST_CODE:
            switch (resultCode) 
            {
                case Activity.RESULT_CANCELED:
                    Log.i(LOG_TAG, "no permission granted, exit");
                    finish();
                case Activity.RESULT_OK:
                    Log.i(LOG_TAG, "permissions granted, start the location service");
                    startLocationService();
                    break;
                default:
                    break;
            }
            break;
    }
}

Binding to the NEON API

In order to start the NEON Location Service and begin tracking, you need to call Neon.bind(). Generally, you want to pass the application context here. Events passed out of the NEON Location Service to your application will be received on the eventHandler you supply, or the Main Looper if you don’t specify.

Neon.unbind() should be called when you application no longer wants to receive events and location updates. If your application is the only one bound to the NEON Location Service, it will be shutdown once you unbind.

NOTE: You should not call Neon.bind() if your application is already bound - an exception will be thrown. You can check whether you are currently bound with Neon.isBound().

boolean bind(Context c, Handler eventHandler)
void unbind()
boolean isBound()

Registering for Events

The NEON Location Service will send events to notify any connected applications about state changes. Some events are status notifications about battery life, or tracking quality. Others indicate that authentication is needed or that the NEON Location Service needs to be upgraded.

void registerEvents(INeonEventListener listener)
boolean unregisterEvents(INeonEventListener listener)

Events will be returned on the INeonEventListener’s onEvent() function.

Registering for Locations

Once the NEON Location Service has been bound, locations will be sent to all registered applications. Implement an INeonLocationListener and choose a NeonLocationType.

NeonLocationType Description
Current Only the most up-to-date locations
Per Step The location at every step
Corrected Updates locations in the past as NEON Location Service corrects them

Locations will be returned on the INeonLocationListener’s onLocationChanged() function. Make sure to unregister your listener when you unbind from the NEON Location Service.

void registerLocationUpdates(INeonLocationListener listener, NeonLocationType type)
boolean unregisterLocationUpdates(INeonLocationListener listener)

Providing Credentials

To enter credentials you can call the NEON Login Activity. This will allow the user to enter a user name and password or sign in with a Google account.

Generally, an application should call this function when it receives an Authentication event with type NO_CREDENTIALS_SET. The user will need to enter credentials into the NEON login activity. A request code can be returned to the calling activity to indicate whether the user exited without entering credentials. The NEON Location Service will indicate that it has successfully logged in with an Authentication event of type SUCCESS. Before this event, API functions which require a login will fail.

boolean startLoginActivityForResult(int requestCode, Activity visibleActivity)

Selecting a NEON Tracking Unit

NEON Location Service needs a selected tracking unit in order to start tracking and acquire a location. To check whether a tracking unit has been selected, call Neon.hasTrackingUnit(). In order to bring up the tracker selection activity, call Neon.startTrackingUnitActivityForResult(), which will launch an activity to guide the user in connecting to a tracking unit.

boolean hasTrackingUnit()
boolean startTrackingUnitActivityForResult(Activity visibleActivity, int requestCode)

Updating the NEON Location Service

If there is an available update, calling Neon.upgradeNeonLocationServices() will launch an activity that will download and install the latest version of the NEON Location Service. This only needs to be called when an UpdateAvailableEvent or MandatoryUpdateAvailableEvent is received. Note that if you upgrade the NEON Location Service while bound, the service will be forced to unbind. A binding event of type FATAL_DISCONNECT will be received, and you should unbind and unregister listeners on that event. Once the new version is installed, you can rebind to Neon.

The NEON Location Service is updated regularly, and upgrades are not required for continued operation. However, a MandatoryUpdateAvailable event means that the NEON Location Service is no longer compatible with the current version of the NEON API, and upgrade is required for continued use. To present the user with a mandatory update, set mandatoryUpdate to true.

void upgradeNeonLocationServices(Activity visibleActivity)
void upgradeNeonLocationServices(Activity visibleActivity, int requestCode, boolean mandatoryUpdate)

Check whether NEON Location Service is Installed

This function can verify whether the NEON Location service is installed on the phone.

boolean isNeonInstalled(Context c)