Alohar Android SDK Reference Guide

v0.2

Last update: 05/25/2012

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

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.

void startService();

      Parameters:
      None

void stopService();

      Parameters:
      None

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.

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)

Register a listener for events of any place.

      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:

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:

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:

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:

Motion State Manager

Besides places, Alohar SDK provides some powerful APIs for applications to get motion state information (@see MotionState), such as stationary, walking, or driving. Since version 0.2, we added some new high level movement recognition APIs (@see MovementState). You need to get the motion manager instance first from Alohar context.

Our SDK applies some smoothing logic on top of the raw motion sensor signals from device. The output is our motion state. Therefore, motion states are quite low level and subject to the quality of the raw sensor data. It has smaller smoothing window and it is stateless, sensitive and real time. Games might be the best type of Apps to use this API.

Our movement APIs is one more level up comparing to motion state APIs. It leverages not only the motion states but also other signals. It has large smoothing window and it is stateful, which makes it more close to human's natual movement pattern. For example, if you stop couple minutes in front of the red light, our motion state APIs might call back with stationary state during that time. Our movement APIs will weight the signals into the previous movement context and decide the state is still driving. If your App needs to trigger actions when users are in some high level states, movement APIs might be a better fit.

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 and movement states.

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.

Similarly, app can also listen movement state events, by using the following real time event listener .

ALMovementListener

Provides the callbacks for the mobile movement state change events.

Callback Methods:

void onMovementChanged(MovementState oldState, MovementState newState):

Called when a new movement state is detected.

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

NOTE: SLOW_MOVING usually indicates walking, biking and slow driving. FAST_MOVING usually indicates high speed driving.

Method References

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

void registerMotionListener(ALMotionListener listener)

Register a listener for motion state changes.

      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.

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.





curl -X POST -d "name=Alohar SDK Reference" --data-urlencode content@reference.md http://documentup.com/compiled?name=super%26 > android_reference.html && open android_reference.html