Alohar SDK Reference v0.5
Overview
The Alohar SDK provides access to the Alohar Mobile Location Behavior Platform, which provides detailed information about the behavior of users by analyzing location and other sensor data. The overall platform is a combination of a smartphone client SDK (for both 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 user in real time and also provide insights over time. These features allow us to provide much more advanced functionality than a conventional location based service (LBS).
This is the reference documentation for the SDK. If this is your first time working with the SDK, we recommend the getting started guide for a short how-to on getting Alohar up and running. If you have a specific question about a method or class, please see the included API documentation.
Initialization / Session Delegate
The SDK provides a single global interface to manage its core service and other major components. Through the Alohar context, the developer can manage the core service, place manager and motion manager. By calling the register or authenticate methods, a new Alohar session is initialized and monitoring can begin.
Alohar SDK does not require a username for end-users 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 requires the app developer to register each of their user with the Alohar SDK using [Alohar registerWithAppID:andAPIKey]
. Note that the developer does not need to pass the application-specific username to Alohar SDK. registerWithAppID
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, your app must manage the userID to allow data retrieval in the future.
Active Methods
registerWithAppID:andAPIKey:withDelegate
Call this method to start an Alohar session for a new user. Your app ID and API key are used to associate this user with your Alohar developer account.
+ (void)registerWithAppID:(NSString *)appID
andAPIKey:(NSString *)APIKey
withDelegate:(id<ALSessionDelegate>)delegate;
Example:
[Alohar registerWithAppID:@
andAPIKey:@
withDelegate:self];
Parameters
- appID: The app ID you were given when you created your Alohar developer account. This is an
NSString
.
- APIKey: The private identifier for your Alohar developer account. This is a hexadecimal
NSString
.
- delegate: The object supporting
ALSessionDelegate
passed to this function will receive session callbacks. See callbacks in this section for further details.
authenticateWithAppID:andAPIKey:andUserID:withDelegate
Use this method when you have an existing user token to associate this account with. This is only necessary for associating a single user across multiple devices.
+ (void)authenticateWithAppID:(NSString *)appID
andAPIKey:(NSString *)APIKey
andUserID:(NSString *)userID
withDelegate:(id<ALSessionDelegate>)delegate;
Parameters
- appID: The app ID you were given when you created your Alohar developer account. This is an
NSString
.
- APIKey: The private identifier for your Alohar developer account. This is a hexadecimal
NSString
.
- userID: The unique
NSString
identifier for the current user. You can get this string by using registerWithAppID
above.
- delegate: The object supporting
ALSessionDelegate
passed to this function will receive session callbacks. See callbacks in this section for further details.
startMonitoringUser
This starts the motion and location monitoring, which is necessary for collection of userstays and motion state. .
[Alohar startMonitoringUser]
stopMonitoringUser
This ends the motion and location monitoring, which is necessary for collection of userstays and motion state. When this method is called, all user data collection and transmission is stopped. No further location data or motion data will be available until startMonitoringUser is called again.
[Alohar stopMonitoringUser]
Callbacks
aloharDidLogin
This method is called by Alohar when a user is successfully logged in. The user ID is a globally unique NSString
that identifies that user across devices. If you pass this ID in the authentication method, Alohar will be able to use the existing user data across devices and installs. This callback is a good time to call startMonitoring user to begin data collection.
- (void)aloharDidLogin:(NSString *)userID;
Parameters
- userID: This is a unique
NSString
that can be used to identify a user across devices.
aloharDidFailWithError
This method is called when there is an issue with the Alohar service. This can be due to a failed signup/login, or an unexpected termination of service. This method will also be called when location is not available for a user (either because of user preference or device issues).
- (void)aloharDidFailWithError:(NSError *)error;
Request Delegate
Alohar's request structure allows queries to be made against the collected data. A query can be made using one of the active methods below, and the result will be returned in an ALResponse
object.
Active Methods
There are several methods to search for a user's previous stays.
getUserStaysForDate:withDelegate
Calling this method with an NSDate
will return all user stays that overlap with that 24-hour period.
+ (void)getUserStaysForDate:(NSDate *)date
withDelegate:(id <ALRequestDelegate>)delegate;
getUserStaysFromDate:toDate:withDelegate
This method returns all user stays that overlap with the period between two NSDate
s.
+ (void)getUserStaysFromDate:(NSDate *)startDate
toDate:(NSDate *)endDate
withDelegate:(id <ALRequestDelegate>)delegate;
getUserStaysFromDate:toDate:atLocation:radius:limit:withCandidiates:withDelegate
Get user's user stays within a time period and a location boundary.
+ (void)getUserStaysFromDate:(NSDate *)startDate
toDate:(NSDate *)endDate
atLocation:(CLLocation *)location
radius:(NSInteger)radius
limit:(NSInteger)limit
includeCandidiates:(BOOL)includeCandidates
withDelegate:(id<ALRequestDelegate>)delegate;
Parameters
- startDate: The start time
- endDate: The end time
- location: The centroid location of the search area. Optional (pass nil to skip).
- radius: The search radius in meter. Optinal (pass nil to skip). Skip if the location is not provided.
- limit: The limitation of total number matches to return. Optional (pass nil to skip). The default is 500.
- withcand: Flag to indicate whether the user stay shall include its candidates. The default is NO.
- delegate: A delegate comforming to protocol
ALRequestDelegate
.
getAllPlacesWithDelegate:withDelegate
This method returns all ALPlace
s that the user has ever visited. NOTE: The response size depends on total number of visits -- for long-term users, this can be hundreds of KB. We recommend using getPlaces:withCategory:withDelegate to return more manageable results.
+ (void)getAllPlacesWithDelegate:(id )delegate;
getPlaces:withDelegate
This method returns all ALPlace
s that match the namePattern
regex NSString
passed to it. For example, passing @"^McDo"
will return all places with names that start with @"McDo" (likely a list of McDonalds visits).
+ (void)getPlaces:(NSString *)namePattern
withDelegate:(id<ALRequestDelegate>)delegate;
getPlaces:withCategory:withDelegate
This method returns all ALPlace
s that match the namePattern
regex NSString
passed to it. For example, calling [Alohar getPlaces:@".*" withCategory:@"^rest" withDelegate:self]
will return all places with categories starting with rest -- likely a list of restaurants and possibly rest stops.
+ (void)getPlaces:(NSString *)namePattern
withCategory:(NSString *)catPattern
withDelegate:(id<ALRequestDelegate>)delegate;
getPlaces:fromDate:toDate:minimalVisits:withCategory:limit:withDelegate
This is the most advanced filter we provide for user stays. See the "Parameters" section below for guidance on each value.
+ (void)getPlaces:(NSString *)namePattern
fromDate:(NSDate *)startDate
toDate:(NSDate *)endDate
minimalVisits:(NSInteger)visits
withCategory:(NSString *)catPattern
limit:(NSInteger)limit
withDelegate:(id<ALRequestDelegate>)delegate;
Parameters
- startDate: The start date.
- endDate: The end date.
- location: The centroid location of the search area. Optional (pass nil to skip).
- radius: The search radius in meter. Optinal (pass nil to skip). Has no effect if location is not provided.
- limit: The maximum number of matches to return. Pass nil for default (500).
- withcand: Flag to indicate whether the user stay shall include its candidates. The default is NO.
- delegate: A delegate comforming to protocol
ALRequestDelegate
.
getPlaceCandidatesForStay:withDelegate
This method returns all of the possible places a user stay could refer to. The Alohar SDK attempts to choose the right place, but orders all possibilities into a candidate list.
+ (void)getPlaceCandidatesForStay:(ALUserStay *)stay
withDelegate:(id<ALRequestDelegate>)delegate;
getStaysForPlace:withDelegate
This method returns all user stays for a given place.
+ (void)getStaysForPlace:(ALPlace *)place
withDelegate:(id<ALRequestDelegate>)delegate;
getDetailsForPlace:withDelegate
This method returns the full details for a place.
+ (void)getDetailsForPlace:(ALPlace *)place
withDelegate:(id<ALRequestDelegate>)delegate;
getDetailsForStay:withDelegate
This method returns the full details for a user stay.
+ (void)getDetailsForStay:(ALUserStay *)stay
withDelegate:(id<ALRequestDelegate>)delegate;
Callbacks
- (void)aloharRequestFinished:(ALResponse *)response;
This method returns an ALResponse
object with the requested data. See the ALResponse
object below.
- (void)aloharDidFailWithError:(NSError *)error;
This callback means something went wrong with the request. The error object describes the issue.
Change Delegate
The change delegate allows you to receive callbacks when the user's state changes. This includes motion state (e.g. walking, driving), as well as location and user stay updates.
Active Methods
setMotionDelegate
Use this method to register for motion state callbacks. If Alohar is currently monitoring the user (see startMonitoringUser
), Alohar will call didUpdateToMotionState:fromMotionState
on this delegate when the user changes their motion state.
+ (void)setMotionDelegate:(id <ALMotionDelegate>)delegate;
setUserStayDelegate
Use this method to register for user stay callbacks. If Alohar is currently monitoring the user (see startMonitoringUser
), Alohar will call userArrivedAtPlaceWithLocation
, currentUserStayIdentified
, and userDepartedPlaceWithLocation
on this delegate (see callback descriptions below).
+ (void)setUserStayDelegate:(id <ALUserStayDelegate>)delegate;
Callbacks
didUpdateToMotionState:fromMotionState
This callback is sent to the delegate when Alohar detects that the user has changed their motion state. See the ALMotionState
object for possible user states.
- (void)didUpdateToMotionState:(ALMotionState *)newMotionState
fromMotionState:(ALMotionState *)oldMotionState;
userArrivedAtPlaceWithLocation
This callback is sent to the delegate when Alohar detects that the user has arrived at a new place. This callback only includes latitude and longitude -- once the place of the stay has been determined, the delegate will receive currentUserStayIdentified
.
- (void)userArrivedAtPlaceWithLocation:(CLLocation *)location;
userDepartedPlaceWithLocation
This callback is sent to the delegate when Alohar detects that the user has left their current place. This callback includes the latitude and longitude of the place the user has left.
- (void)userArrivedAtPlaceWithLocation:(CLLocation *)location;
currentUserStayIdentified
This callback is sent to the delegate when Alohar detects a new user stay. This ALUserStay
object includes location, place name, and several other valuable pieces of data. See the ALUserStay
object for further details.
- (void)currentUserStayIdentified:(ALUserStay *)newStay;
aloharDidFailWithError
This callback is sent to the delegate when an error occurs with either motion state or user stays
- (void)aloharDidFailWithError:(NSError *)error;
Non-delegate methods
These methods return immediately. They are called directly on the Alohar
class -- for example, to get the current user stay, simply call [Alohar currentUserStay]
.
currentUserStay
This returns the user stay the user is currently in, or nil if no user stay exists.
+ (ALUserStay *)currentUserStay;
currentLocation
This returns the latest known location for the user.
+ (CLLocation *)currentLocation;
currentLocation
This returns the current motion state for the user. See ALMotionState
for possible states.
+ (ALMotionState *)currentMotionState;
isStationary
This method returns TRUE if the device is not moving, FALSE in all other cases.
+ (BOOL)isStationary;
isStationary
This method returns FALSE if the user is currently staying at a place, TRUE in all other cases.
+ (BOOL)isBetweenUserStays;
monitoringUser
This method can be used to see if Alohar is tracking the user, and will return TRUE if user monitoring is on.
+ (BOOL)monitoringUser;
monitoringUser
This method returns TRUE if the user has valid credentials and has an active Alohar session, FALSE in all other cases.
+ (BOOL)isLoggedIn;
Objects
Alohar provides a few object types to make using our data easier.
ALUserStay
The ALUserStay
object represents a user's visit to a place.
Properties
NSInteger stayID
The unique identifier for this user stay
CLLocation *centroidLocation
The estimated location of the user stay
NSInteger startTime
Unix time the user arrived at this location
NSInteger endTime
Unix time the user left this location
ALPlace *selectedPlace
The place Alohar believes corresponds to this visit
NSArray *candidates
The full list of possible place options
ALPlace
The ALPlace
object represents a point of interest, e.g. a coffee shop.
Properties
NSInteger placeID;
The unique identifier for this place
NSInteger visitCount
The number of times the user has visited this place
NSString *name
*The name of this place, e.g. "Pizza Hut"
CLLocation *location
The location of the center of this place.
NSString *address
The street address
NSString *phone
The phone number if available
NSString *iconURL
URL for an icon that depicts this place's category
NSString *webURL
URL for the Google Places page for this place
NSString *category
Description of the type of place, e.g. Home
NSString *subCategory
More detailed description, e.g. Italian Bistro
ALMotionState
The ALMotionState
object represents a category of motion from the user.
Possible Motion States:
ALMotionStateStationary
ALMotionStateWalking
ALMotionStateDriving
ALMotionStateNoData
ALMotionStateBigMove
Property
NSNumber *state
The raw state value (see above to find the meaning of each number
Call [motionState stateDiscription]
for a pretty NSString
version of the current state. Possible values are Stationary
, Big Move
, Driving
, Walking
, and unknown
.
- (NSString *)stateDescription;
ALResponse
The ALResponse
object is a wrapper for the return values for all requests to the Alohar service.
Request Types:
kALRequestTypeUserStays,
kALRequestTypePlaces,
kALRequestTypeMotionState,
kALRequestTypeStayDetail,
kALRequestTypePlaceDetail
Properties
NSDate *timeStamp
The date that this request was returned
NSMutableArray *objects
*The returned values from the request. Even if there is only one result, it will always be wrapped in an NSMutableArray
.
ALRequestType requestType
*The type of request this response is from. See Request Types above for the available options.
curl -X POST -d "name=Alohar SDK" --data-urlencode content@documentation.md http://documentup.com/compiled?name=super%26 > documentation.html && open documentation.html