Alohar Android SDK Reference Guide

v0.5

Alohar Mobile Inc develops the Alohar Mobile Location Behavior Platform, which understands mobile device user’s behavior by analyzing location and other mobile sensor data. The platform is composed of a smartphone client SDK (software development kit) for Android and iPhone and several cloud-based services. The Alohar Mobile Location Behavior Platform uses mobile location, motion, wifi and timing data to learn about the mobile device user in real time and over time. Therefore it provides more advanced functionality than a conventional mobile LBS (location based services) platform.

Please read Alohar Developer APIs for a high level overview of the platfrom. To learn how to set up the Alohar Android SDK, please read the Android Tutorial.

In this reference guide, we use "the developer" and "you" interchangeably.

Overview

The Alohar SDK consists of four major components:

Configuration and UserId Management
Core Service Management
Place and Userstay Management
Motion State Management

Configuration and UserId Management

To start using the SDK, a developer needs to do the following three steps:

Environment Configuration

The following permissions are required for SDK to function, the developer needs to add them in the manifest file.

 <!-- permissions for the Alohar SDK -->
<uses-permission android:name="android.permission.INTERNET" />
<uses-permission android:name="android.permission.ACCESS_FINE_LOCATION" />
<uses-permission android:name="android.permission.ACCESS_COARSE_LOCATION"/>
<uses-permission android:name="android.permission.READ_PHONE_STATE" />
<uses-permission android:name="android.permission.ACCESS_WIFI_STATE" />
<uses-permission android:name="android.permission.WAKE_LOCK"/>
<uses-permission android:name="android.permission.RECEIVE_BOOT_COMPLETED"/>

The SDK runs as Android services in the background. The app must register the services in the manifest file:

<!-- services -->
<service android:enabled="true" android:name="com.alohar.core.ALCoreService"/>
<service android:enabled="true" android:name="com.alohar.core.ALMasterService"/>

Alohar Context Initialization

The SDK provides a single global interface or context to manage its core service and other major components. The singleton instance shall be initialized by calling Alohar.init() when the App starts. Once it is initialized, the instance can be accessed in the application by using Alohar.getInstance(). Through the Alohar context, the developer can manage the core service, place manager and motion manager.

As the very first action to use Alohar SDK, the app has to call the following method to initialize the Alohar context. It is recommended to be called when the application is initialized or in the onCreate method of the root activity:

static void Alohar.init(Application context)

Parameters:
context: application context

After the Alohar is initialized, the developer can use the following method to get the global Alohar instance. This is also referred to as the Alohar context in the following description.

static Alohar Alohar.getInstance()

Parameters:
None

UserId Registration/Authentication

Alohar SDK does not require a username for the end-user of the app that the developer builds. Typically, the developer manages the personally identifiable user information themselves, such as keeping track of the email addresses of their users. Alohar does NOT need such user info.

However, Alohar SDK does require the app developer to register each of their user with Alohar SDK, using Alohar.register(). Note that the developer does not need to pass the application-specific username to Alohar SDK. Alohar.register() generates a unique UserId (UID). This UserId is for Alohar SDK to manage the specific user’s info.

It is the developer’s responsibility to record the unique UID generated by register() to do authentication and retrieve data from Alohar in the future.

The developer is responsible to maintain the mapping of their users and the Alohar userids.

The second time the app is run for the specific user, the app uses the UID and calls Alohar.authenticate() from Alohar context to authenticate the user. Once the user is authenticated, the app can start to manage the core service and access user information from Alohar platform.

User Registration

After the Alohar context is initialized, the developer needs to register and authenticate their user in Alohar system. The SDK manages the authentication and authorization and securely communicate with the Alohar servers.

To register a new end user of the developer’s app, use the following register method of the Alohar class, which returns an unique UserId (UID) if the call is valid. Again, THE APP SHALL MANAGE THE ID PROPERLY TO RETRIEVE DATA IN THE FUTURE.

void register(int appId, String apiKey, ALEventListener callback)

      Parameters:
      appId: the application ID granted from Alohar when developer registered its application.
      apiKey: the unique key assigned to the given application granted from Alohar.
      callback: event listener ALEventListener (@see Common Interfaces). It will be called with REGISTER_CALLBACK event if the operation is successful, which returns a userid, among other info.

User Authentication

For an existing user, call the following method to authenticate it, using the UID you have obtained from Alohar.register() in a previous run.

void authenticate(String uid, int appId, String apiKey, ALEventListener callback)

      Parameters:
      uid: unique user id assigned to this user of the given application, obtained from Alohar.register() in a previous run.
      appId: application ID granted from Alohar when developer registered its application.
      apiKey: unique key assign to given application granted from Alohar.
      callback: event listener ALEventListener (@see Common Interfaces). It will be called with AUTHENTICATE_CALLBACK event if the operation is successful.

After the app has valid UID, the application can start the core service of the SDK and utilize its power.

Core Service Management

The core service is the key component of the SDK. It intelligently collects sensor signals (e.g., GPS, wifi, accelerometer) and maintains the real time communication with the Alohar server system.

The developer can manually start the core service by calling Alohar.startService() from Alohar context. The started service can also be manually stopped by calling Alohar.stopService().

The service will auto restart when the device reboots if the App does not stop it before it quits. The auto-start feature is desirable to provide best performance to the app’s end user. It is enabled by default, the developer can turn it on by adding the following lines in the manifest file:

<receiver android:name="com.alohar.core.ALBroadcastReceiver" android:enabled="true">
<intent-filter>
    <action android:name="android.intent.action.BOOT_COMPLETED"></action>
</intent-filter>
</receiver>

To completely shut down all components and release all resources of the SDK, the developer can call tearDown() after calling stopService(), which removes all cached data and resets all component and account information.

Method References

The following methods manage the life cycle of the core service. All these methods are accessible from the class Alohar, which is the global interface to the SDK.

Start core service and set up other dependencies properly.

void startService();

Parameters:
None

Stop core service.

void stopService();

Parameters:
None

Stop all other components and release resource properly. Any methods call after the tear down is not guaranteed.

void tearDown();

Parameters:
None

Place Manager

Alohar SDK provides some very unique functions for one common requested information of every LBS service: place. It is not simply about the location of the user, but also provides interesting info about the place, such as the name of the place, the category of the place (e.g. restaurant and cuisine), the arrival and departure time of each visit of the place. It is automatic, meaning that it does not require manual check-in.

To see how powerful these features are and understand how you can build interesting app on top them, you first need to get an instance of the Place Manager via the Alohar context.

ALPlaceManager getPlaceManager();

Get Alohar place manager where you can register to listen for place events, query or search places and user stays.

Parameters:
None

Returns:
Alohar Place Manager.

The PlaceManager supports the retrieval and search of the following place data types.

Place: detail information of a place visited by a user, including id, name, address, latitude(E6), longitude(E6), category, phone, web, iconUrl.
UserStay: a visit of a place detected by Alohar core service. The stay has one selected place and a list of place candidates. It also stores an Alohar computed centroid (latitude, longitude) for reference in addition to other meta data including start time, end time, state, feedback, parent etc.
PlaceProfile: a statistic profile of a place including visit count, time of first and last visit.
ALLocation: a location entity used by Alohar service. It has latitude and longitude.

Real Time Userstay Interface

PlaceManager supports real time place detection, for example, when the user arrives at or leaves a place, certain events are generated. Developers can use the following callback interface to listen to those events.

ALPlaceEventListener

Provides callbacks for events when user arrives at or leaves a place.

Callback Methods:

void onArrival(double latitude, double longitude);

Called when user arrives at a place. It provides the place’s location.

      Parameters:
      latitude: double e.g. 34.432110
      longitude: double e.g. -122.103274

void onDeparture(double latitude, double longitude);

Called when user leaves a place with the place’s location

      Parameters:
      latitude:double
      longitude:double

void onUserStayChanged(UserStay userStay);

Called when current userstay changes. Either a new userstay is detected, or some major attributes of the current userstay has changed.

Parameters:
userStay: updated current user stay with candidate list.

Method Reference

The developer can use the following methods of ALPlaceManager to get place-related data.

ALLocation getCurrentLocation()

Get current alohar location

Parameters:
None

UserStay getLastKnownStay()

Get last known user stay which might be different from the real current user stay depends on the alohar service. It shall be the current user stay in most cases.

Parameters:
None

void registerPlaceEventListener(ALPlaceEventListener listener)

Parameters:
listener: callback. See ALPlaceEventListener.

void registerPlaceEventListener(ALPlaceEventListener listener, String namePattern, String categoryPattern)

Register a listener for place events, including arrival and departure. The event can be further filtered by place name or category using regular expressions.

      Parameters:
      listener: callback. See ALPlaceEventListener.
      namePattern: regular expression to match the place’s name.
      categoryPattern: regular expression to match the place’s category.

void searchPlaces(long startTime, long endTime, String categoryPattern,   int visitCountFilter, int limit, final ALEventListener callback)

Search visited places in a time window. The result can be further controlled by category filter, visit count filter. The total number of result is capped by the limit variable with default value=500.

      Parameters:
      startTime: start time in seconds.
      endTime: end time in seconds.
      categoryPattern: regular expression to match the places, null to match all category.
      visitCountFilter: matches places with visitcount >= visitCountFilter.
      limit: maximal result to return.
      callback: ALEventLisener. The following events will be called back:

If successful, ALEvents.PLACES_QUERY_CALLBACK. Data is a list of PlaceProfile.
If failed, ALEvents.GENERAL_ERROR_CALLBACK or ALEvents.SERVER_ERROR_CALLBACK. Data is the error message if available.

void getUserStays(Place place, final ALEventListener callback)

Fetch all user stays of a given place.

      Parameters:
      place: a place
      callback: ALEventLisener. Following events will be called back:

If successful, ALEvents.USERSTATS_OF_A_PLACE_CALLBACK. Data is a list of UserStay.
If failed, ALEvents.GENERAL_ERROR_CALLBACK or ALEvents.SERVER_ERROR_CALLBACK. Data is the error message if available.

void searchUserStays(double latitude, double longitude, int radius, long startTime, long endTime, boolean withCandiates, int limit, ALEventListener callback)

Search user stays around a location in a time window. The total number of results is capped by the limit variable, with default=500.

      Parameters:
      latitude: latitude [-90,+90].
      longitude: longitude [-180,+180].
      radius: in meters > 0.
      startTime: start time in seconds.
      endTime: end time in seconds.
      withCandiates: true if want to fetch candidate list in each user stay.
      limit: maximal result to return.
      callback: ALEventLisener. The following events will be called back:

If successful, ALEvents.USERSTAYS_QUERY_CALLBACK. Data is a list of UserStay.
If failed, ALEvents.GENERAL_ERROR_CALLBACK or ALEvents.SERVER_ERROR_CALLBACK. Data is the error message if available.

void getCandidates(UserStay stay, ALEventListener callback)

Fetch the place candidate list of a given user stay.

      Parameters:
      stay: a user stay
      callback: ALEventLisener. Following events will be called back:

If successful, ALEvents.USERSTAY_CANDIDATES_CALLBACK. Data is a list of Place.
If failed, ALEvents.GENERAL_ERROR_CALLBACK or ALEvents.SERVER_ERROR_CALLBACK. Data is the error message if presents.

Motion State Manager

Besides places, Alohar SDK provides some powerful APIs for applications to get motion state information, such as stationary, walking, or driving. You need to get the motion manager instance first from Alohar context.

ALMotionManager getMotionManager();

Get motion manager where you can register to listen for motion state change, query user’s current motion state etc. see more here.

Parameters:
None

Returns:
Alohar Motion Manager.

Data Elements

Currently, Alohar SDK supports the following motion states.

MotionState: a set of motion states supported such as STATIONARY, WALKING, MICROMOVEMENT etc.

Real-Time Interfaces

The developer’s app can receive real-time events when user’s motion state changes, by using the following real time event listener.

ALMotionListener

Provides the callbacks for the motion events.

Callback Methods:

void onMotionStateChanged(MotionState oldState, MotionState newState):

Called when a new motion state is detected.

      Parameters:
      oldState: old motion state.
      newState: new motion state.

Method References

Methods to listen or query device’s motion state through ALMotionManager.

void registerMotionListener(ALMotionListener listener)

Parameters:
listener: motion listener. See ALMotionListener.

MotionState getCurrentMotionState()

Query user’s current motion state.

Parameters:
None

boolean isStationary()

Check whether user is not moving.

Parameters:
None

boolean isOnCommute()

Check whether user is on the road or not at a place.

Parameters:
None

Returns:
True if user is on the road. Otherwise False.

Common Interfaces

ALEventListener is the key interface to interact with Alohar SDK from your Application. The SDK defines a set of events indicating the status of your request to Alohar platform. We use this event model to make all your service call asynchronous so that you don’t need to worry about the performance and focus more on developing your own killing features. The result of your request to Alohar platform will be made available to you automatically through a callback when it is ready.

ALEvents: a set of events used for Alohar service callback.
ALEventListener

Provides callback for alohar service request.

Callback Methods:

void handleEvent(ALEvents event, Object data);

      Called when an alohar service request is completed. The following event of type ALEvent are supported:
      •   GENERAL_ERROR_CALLBACK: connection error or other general failures.
      •   SERVER_ERROR_CALLBACK: server request failure.
      •   USERSTAY_QUERY_CALLBACK: callback event for user stay query.
      •   PLACES_QUERY_CALLBACK: callback event for places query.
      •   USERSTAY_OF_A_PLACE_CALLBACK: callback event for user stay query of a given place.
      •   USERSTAY_CANDIDATES_CALLBACK: callback event for query place candidates.
      •   REGISTRATION_CALLBACK: callback event when a new user is successfully registered.
      •   AUTHENTICATE_CALLBACK: callback event when the alohar service is properly authenticated.

      Parameters:
      event: alohar event.
      data: misc data attached to the callback.

New Feature Requests & Questions

Alohar Android SDK is still in the beta state. We are working on new and cool features. If you have any new API feature requests or questions about the SDK, please contact us at: developer@alohar.com.

Alohar Android SDK Reference Guide

Overview

Configuration and UserId Management

Environment Configuration

Alohar Context Initialization

UserId Registration/Authentication

User Registration

User Authentication

Core Service Management

Method References

Place Manager

Major Place-Related Data Types

Real Time Userstay Interface

Method Reference

Motion State Manager

Data Elements

Real-Time Interfaces

Method References

Common Interfaces

New Feature Requests & Questions