Alohar SDK Reference

Overview

Alohar offers a mobile device Location Behavior Platform allowing developers to respond user behaviors by analyzing location and device sensor data. Alohar delivers real time device data from location, motion, wifi and timing data. Its advanced functionality gives competitive advantages in applications than a conventional location based services (LBS) platform.

Alohar platform is now available for iOS SDK and Android SDK. Alohar SDK is ideal for applications such as smart personal assistants, location-based games, mobile health apps, mobile shopping/coupon apps, social networking apps and mobile dating apps.

Smart things you can do with the Alohar SDK

The beauty of the Alohar SDK is that you can focus on your application-specific functionalities, rather than low level user location and behavior, and therefore achieve a fast time to market.

For Alohar Beginners. We recommend you to review getting started guide. For details on a method or class, please refer to the Alohar API documentation.

Alohar SDK Requirements

Alohar SDK requires Xcode 4.2+ for development, and iOS 5.0+ for both development and distribution and to access advanced location features of iOS. You can update your software from Apple's developer portal: developer.apple.com.


Initialization / Session Delegate

Alohar SDK provides a single global interface to manage its core service and other major components. Developer can manage the core service, place manager and motion manager within Alohar SDK. By calling the register or authenticate methods, a new Alohar session is initialized and monitoring can begin.

Alohar handles the developer’s identity in an anonymous fashion. The developer manages the authentication of their own application end-users. Alohar does not require the identity of the users of the third-party application. Instead, the application developer only provides an anonymous user id to Alohar, which Alohar uses to manage each user’s data. This way, Alohar never sees the real identity of the user of the developer’s application.

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. Alohar 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.

You can obtain AppleID by following the steps in getting started guide.

+ (void)registerWithAppID:(NSString *)appID
                andAPIKey:(NSString *)APIKey
             withDelegate:(id<ALSessionDelegate>)delegate;

Example:

[Alohar registerWithAppID:@"appID" 
                andAPIKey:@"APIKey"
             withDelegate:self];
Parameters

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

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

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 (it can be determined by user preference or caused by device issues).

- (void)aloharDidFailWithError:(NSError *)error;

Request Delegate

Alohar's request structure allows queries to be made against the collected data. Each of these queries uses blocks to return the results asynchronously. Here's an example:

Method:

+ (void)getDetailsForStay:(NSInteger)stayId
               completion:(void (^)(ALResponse *response, NSError *error))completion;

Usage:

[Alohar getDetailsForStay:stayID completion:^(ALResponse *response, NSError *error) {
    if (error) {
        NSLog(@"Request Failed. Error %@", error);
    } else {
        NSLog(@"Request Succeeded!");
        //The resulting user stay is stored in the variable 'response'
    }
}];

Active Methods

There are several methods to search through a user's stay history.

getUserStaysForDate:completion

Calling this method with an NSDate will return all user stays that overlap with that 24-hour period.

+ (void)getUserStaysForDate:(NSDate *)date
                 completion:(void (^)(ALResponse *response, NSError *error))completion;

getUserStaysFromDate:toDate:completion

This method returns all user stays that overlap with the period between two NSDates.

+ (void)getUserStaysFromDate:(NSDate *)startDate
                      toDate:(NSDate *)endDate
                  completion:(void (^)(ALResponse *response, NSError *error))completion;

getUserStaysFromDate:toDate:atLocation:radius:limit:includeCandidiates:completion

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
                   completion:(void (^)(ALResponse *response, NSError *error))completion;
Parameters

getAllPlacesWithCompletion

This method returns all ALPlaces 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)getAllPlacesWithCompletion:(void (^)(ALResponse *response, NSError *error))completion;

getPlacesWithPattern:completion

This method returns all ALPlaces 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)getPlacesWithPattern:(NSString *)namePattern
                  completion:(void (^)(ALResponse *response, NSError *error))completion;

getPlacesWithPattern:andCategory:completion

This method returns all ALPlaces 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)getPlacesWithPattern:(NSString *)namePattern
                andCategory:(NSString *)catPattern
                  completion:(void (^)(ALResponse *response, NSError *error))completion;

getPlacesWithPattern:fromDate:toDate:minimalVisits:withCategory:limit:completion

This is the most advanced filter we provide for user stays. See the "Parameters" section below for guidance on each value.

+ (void)getPlacesWithPattern:(NSString *)namePattern
         fromDate:(NSDate *)startDate
           toDate:(NSDate *)endDate
    minimalVisits:(NSInteger)visits
     withCategory:(NSString *)catPattern
            limit:(NSInteger)limit
       completion:(void (^)(ALResponse *response, NSError *error))completion;
Parameters

getPlaceCandidatesForStay:completion

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:(NSInteger)stayId
                       completion:(void (^)(ALResponse *response, NSError *error))completion;

getStaysForPlace:completion

This method returns all user stays for a given place.

+ (void)getStaysForPlace:(NSInteger)placeId
              completion:(void (^)(ALResponse *response, NSError *error))completion;

getDetailsForPlace:completion

This method returns the full details for a place.

+ (void)getDetailsForPlace:(NSInteger)placeId
                completion:(void (^)(ALResponse *response, NSError *error))completion;

getDetailsForStay:completion

This method returns the full details for a user stay.

+ (void)getDetailsForStay:(NSInteger)stayId
               completion:(void (^)(ALResponse *response, NSError *error))completion;

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;

userArrivedAtPlace:withLocation

This callback is sent to the delegate when Alohar detects that the user has arrived at a new place. This callback includes latitude and longitude with a optional personal place if it is close enough to the centroid of the arrival -- once the final place of the stay has been determined, the delegate will receive currentUserStayIdentified.

- (void)userArrivedAtPlace:(ALPlace *)personalPlace withLocation:(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 useful object types to give more data details.

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;

ALMobileState

The ALMobileState object represents a category of high level movement from the user.

Possible Mobile States:
   ALMobileStateUnknown
   ALMobileStateNotMoving
   ALMobileStateSlowMoving
   ALMobileStateFastMoving
Property

NSNumber *state The raw state value (see above to find the meaning of each number

Call [mobileState stateDiscription] for a pretty NSString version of the current state. Possible values are Not Moving, Slow Moving, Fast Moving, 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,
    kALRequestTypeStayDetail,
    kALRequestTypePlaceDetail
    kALRequestTypeCorrectUserStay,
    kALRequestTypeAddUserStay,
    kALRequestTypeDeleteUserStay
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, unless it is NIL otherwise 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.




Copyright 2011-2012 Alohar Mobile Inc. All rights reserved.


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