Getting Started

Overview

The Apsima iOS SDK provides an easy way for iOS native apps to integrate with Apsima REST Api.

Back To Top

Download Apsima iOS SDK and Demo

Please contact Apsima for download information.  You can also send an email to support@apsima.com

Back To Top

SDK

Overview of the SDK

Apsima SDK includes a set of frameworks and bundles:

  • KSPBaseSDK
  • KSPProfileSDK
  • KSPNotificationSDK
  • KSPLocationSDK

Back To Top

KSPBaseSDK

KSPBaseSDK provides the basic functionalities for all Apsima frameworks, including API Settings, register devices, etc.

Back To Top

KSPProfileSDK

All Apsima features require the end user logged in and authorized with Apsima Server. KSPProfileSDK provides the functionalities for user account management, e.g. SignUp, Login, Logout, Edit Profile and Change Password.

Back To Top

KSPNotificationSDK

Through Apsima Dashboard or via REST api, the app developer can create, send or schedule a KSP notification to end users. Please consult the ‘Apsima Dashboard Guide’ for more information on how to schedule notifications.

This SDK provides the functionality to manage notifications, e.g. Synchronize, Read or Delete notifications, etc.

Back To Top

KSPLocationSDK

Apsima supports Geofence and Proximity awareness. You can create a Geofence or Proximity trigger to send a notification to a user or call a callback URL.  Please consult the ‘Apsima Dashboard Guide’ for more information on how to manage and use geofence and proximity beacons.

KSPLocationSDK provides the functionality to handle communications between iOS devices and Apsima Platform, e.g. download Geofence and Proximity updates from server, monitor the regions and report the region triggered events. KSPLocationSDK will also pass the failed messages from CLLocationManager to your app when it happens.

Geofence Awareness

When using Apsima’s geofence feature, most of the logic is implemented in the SDK. It will receive and store the geofences to be monitored, register it with iOS, and receive a region triggered event when device has entered or exited a geofence. SDK will also notify your app about this event.

Proximity Awareness

Apsima’s Proximity feature supports 3 different modes, MonitoringGroup, RangingIndividual, and Mixed Mode.

In MonitoringGroup mode, most of the logic is implemented in the SDK. It will receive and store the Beacon Group(s) to be monitored, register them with iOS, and receive a region triggered event when device is within proximity of a Beacon Group. SDK will notify your app about this event. Note that a Beacon Group can have multiple beacons, but SDK is monitoring the Group and not individual beacons. Monitoring can be done when app is in foreground or background.

In RangingIndividual mode, SDK will receive and store the Beacon Groups to be monitored. It will range all the beacons that belong to these Beacon Groups. iOS will only generate region triggered event for beacons that belong to these Beacon Groups. When device detects that it is in proximity of one or more beacons, it will get information about each particular beacon, and report it to your app. RangingIndividual mode is only supported when app is in foreground. When app is in background, it will not trigger the region triggered event.

In Mixed mode, SDK will monitor Beacon Group(s) received from Apsima server. When device enters a Beacon Group’s proximity, SDK will start to range all beacons that belong to this Beacon Group. When device detects the beacons, it will get information about each particular beacon, and report it to your app. When app is in background, it will keep monitoring for Beacon Groups and report triggers to server. Note that in background mode ranging mode is not active.

Back To Top

How it works

KSPBaseSDK

Reference KSPBaseSDK

Simply drag the framework into the App:

reference_ksp_bace_sdk

Add ‘–ObjC’ to the ‘Other Linker Flags’ in target ‘Build Settings’.

Configure KSPAPISettings

Configure KSPAPISettings in application:didFinishLaunchingWithOption: method, using API credentials

1
2
3
4
5
6
7
- (BOOL)application:(UIApplication *)application didFinishLaunchingWithOptions:(NSDictionary *)launchOptions
{
…
    [[KSPAPISettings sharedSettings] configWithApiKey:API_KEY apiSecret:API_CLIENT_SECRET endPoint:API_ENDPOINT sessionKey:DOMAIN_KEY];
 
…
}

API_ENDPOINT is the url to Apsima server. It should be https://rest.apsima.com/

You can grab the other API credentials from Apsima dashboard:

  1. Click on Application tab
  2. Click on API option

ksp_base_sdk_app1

Setup APNS certificate

Follow How to request and generate APNS certificate and upload the Personal Information Exchange (.p12) file of APNS certificate to Apsima Dashboard.

  1. Click on the Application tab under the top header
  2. Click on the API tab on the left
  3. Click on Choose Certificate button in the APNS section
  4. Select the correct file and click Save button.

ksp_base_sdk_app2

Register device

Registering a device allows Apsima Server to target an individual device and send remote push notification to the registered device. There are two values required to register a device, deviceToken and userUid. Two steps to register a device:

1. Register push notification deviceToken

Call KSPDeviceManager registerDeviceWithDeviceTokenData:completion: method in application:didRegisterForRemoteNotificationsWithDeviceToken: method.

1
2
3
4
5
6
- (void)application:(UIApplication*)application didRegisterForRemoteNotificationsWithDeviceToken:(NSData*)deviceToken
{        
    [KSPDevice registerDeviceWithDeviceTokenData:deviceToken completion:^(BOOL success, NSError* error) {
        // Handle the completion here;
    }];
}

Note: UIApplication registerForRemoteNotficationTypes: method gets called inside the SDK while the app is starting.

2. Register userUid

Apsima features require end user to login and be authenticated with Apsima Server. A userUid is unique identifier for logged-in user. You can always retrieve its value from KSPUser.userUid. The best place to register the user with Apsima is right after login.

1
2
3
4
5
6
7
8
- (void) onloggedIn
{
…
    [KSPDevice registerDeviceWithUserUid:userUid completion:^(BOOL success, NSError* error) {  
        // Handles the completion here.
    }];
…
}
Handle Push Notification

This will manage the different type of push notifications. For example, when it received a push notification about new KSPNotification available, then it will notify KSPNotificationManager to handle it.

1
2
3
4
5
6
- (void)application:(UIApplication *)application didReceiveRemoteNotification:(NSDictionary *)userInfo
{
    [KSPNotificationHandler handle:userInfo withApplicationState:application.applicationState];
 
    //Handle your own push notification below.
}

Back To Top

KSPProfileSDK

Reference KSPProfileSDK

Simply drag the framework into the App project:

reference_ksp_profile_sdk

Add CoreData.framework into your project if you haven’t as it is required by KSPProfileSDK.

Initialize KSPProfileManager

KSPProfileManager is the entry point for all functionalities of the KSPProfileSDK. It needs to be initialized before using it.

1
2
3
4
5
6
7
8
- (BOOL)application:(UIApplication *)application didFinishLaunchingWithOptions:(NSDictionary *)launchOptions
{
…
    _profileManager = [[KSPProfileManager alloc] init];
    _profileManager.delegate = self;
 
…
}
Implement KSPProfileManagerDelegate
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
#pragma mark - KSPProfileManagerDelegate
- (void) profileManager:(KSPProfileManager *)manager requestStartingWithRequestType:(ProfileRequestType)actionType
{
   // Handles the status, e.g. show an alert.
}
 
- (void) profileManager:(KSPProfileManager *)manager requestFinishedWithRequestType:(ProfileRequestType)actionType
{
    // Handles the status, e.g. hide the alert.
}
 
- (void) profileManager:(KSPProfileManager *)manager unauthorizedWithUserInfo:(NSDictionary *)userInfo
{
    // Handles the status, e.g. Logout the user.
}

Note: All of the delegate handlers are optional.

Sign up

User can sign up to create a new account by providing full name, username, email and password. Upon successful sign up process, user can use the username password to login to the app.

1
2
3
4
5
{
    [_manager signupUserWithUsername:username fullName:fullName email:email password:password confirmPassword:confirmPassword completion:^(BOOL success, KSPUser* user, NSError* error) {
        // Handles the completion, e.g. Go to main view.
}];
}

Errors:

– Full name is required.

– Username is required.

– Email is required.

– Invalid Email.

– Password is required.

– Password must be 6-32 characters.

– Password and Confirm password must be match.

– Duplicate username.

– Invalid username or Email.

Login

User can login to the app using their username and password. Upon successful login process, SDK will generate an authentication token.

1
2
3
4
5
{
    [_manager loginWithUsername:username password:password completion:^(BOOL success, KSPUser* user, NSError* error) {
        // Handles the completion, e.g. Go to main view. 
    }];
}

Errors:

– Username is required.

– Password is required.

– Password must be 6-32 characters.

– Invalid username or password.

Get Profile

You can use this method to get user’s profile. This method can only be called after user is logged in, otherwise you will get a nil object.

1
2
3
4
5
6
7
{
    KSPProfileManager* manager = [[KSPAppDelegate sharedDelegate] profileManager];
 
    KSPUser * user = [manager getProfile];
 
   // Set user properties. 
}
Update Profile

You can use this method to update user’s profile – i.e. username, full name or email address. This method can only be called after user is logged in.

1
2
3
4
5
6
7
8
{
…
    KSPProfileManager* manager = [[KSPAppDelegate sharedDelegate] profileManager];
 
    [manager updateUserWithUsername:self.usernameText.text fullName:self.fullNameText.text email:self.emailText.text completion:^(BOOL success, NSError* error){       
       // Handle the completion, e.g. Show an alert.
    }];
}

Error:

– Full name is required.

– Username is required.

– Email is required.

– Invalid Email.

Update Profile Image

You can use this method to update user’s profile image, either by taking a new picture or using an existing one. This method can only be called after user is logged in. See ApsimaDemo sample app.

1
2
3
4
5
6
7
{
    NSData* data = UIImagePNGRepresentation(self.profileImageView.image);
 
    KSPProfileManager* manager = [[KSPAppDelegate sharedDelegate] profileManager];
 
    [manager updateUserProfileImageWithData:data completion:nil];
}
Change Password

You can use this method to change user’s password by providing the old password and new password. This method can only be called after user is logged in.

1
2
3
4
5
{
    KSPProfileManager* manager = [KSPAppDelegate sharedDelegate].profileManager;
    [manager changePasswordWithNewPassword:curPwd oldPassword:oldPwd completion:^(BOOL success, NSError* error) {                     // Handle the completion, e.g. Show an alert.
    }];
}

Errors:

– Password is required.

– Password must be 6-32 characters.

– Password and Confirm password must be match.

Back To Top

KSPNotificationSDK

Reference KSPNotificationSDK

reference_ksp_notification_sdk

Add CoreData.framework into your project if you haven’t.

Initialize KSPNotificationManager

KSPNotificationManager is the entry point for all functionalities of the KSPNotificationSDK. It needs to be initialized before using it.

Get Notification Updates

Call getNotificationUpdatesWithCompletion: to get all the potential updates of notifications after initialization.

1
2
3
4
5
6
7
8
9
10
{
…
    self.notificationManager = [[KSPNotificationManager alloc] init];
    self.notificationManager.delegate = self;
 
    [self.notificationManager getNotificationUpdatesWithCompletion:^(BOOL success, NSError * error) {
        // Handle the error here.
    }];
 ...
}
Initialize a fetchedResultController

This will fetch the KSPNotification list from CoreData.

1
2
3
4
5
6
{
    self.fetchedResultsController = [self.notificationManager createNotificationFetchedResultsControllerWithOwnerUid:nil];
    self.fetchedResultsController.delegate = self;
    [self.fetchedResultsController performFetch:nil];
    …
}

Note: ownerUid can be left as nil for now.

Delete a KSPNotification

This will notify server when user deletes a KSPNotification. Server will mark it as deleted and notify user’s other devices (if any) to keep all devices synchronized. This action will affect the metrics reports.

1
2
3
4
5
6
7
8
{
    if (editingStyle == UITableViewCellEditingStyleDelete) {
        KSPNotification* notification = [self.items objectAtIndex:indexPath.row];
 
        [self.notificationManager deleteNotificationWithUid:notification.uid completion:nil];
 
    }
}
Get KSPNotification content

This will get the content of KSPNotification in html format.

1
2
3
4
5
6
7
{
…
    NSError* error;
    NSString* content = [self.notificationManager getNotificationContentWithUid:self.notification.uid error:&error];
 
    [self.webView loadHTMLString:content baseURL: [NSURL URLWithString:[KSPAPISettings sharedSettings].endPoint]];
}

 

Read a KSPNotification

This will notify server when user opens a KSPNotification. It also passes true if it is was open from the iOS Notification Center (or lock screen) and false if opened from within the app.

1
2
3
4
5
6
{
…
    if(![self.notification.isRead boolValue]){
        [self.notificationManager readNotificationWithUid:self.notification.uid fromPushNotification:self.isReadFromNotification completion:nil];
    }
}

Back To Top

KSPLocationSDK

Reference KSPLocationSDK

ref_ksp_location_sdk

Add CoreData.framework and CoreLocation.framework into your project if you haven’t.

Geofence

When using the geofence feature, KSPLocationSDK will handle most of the logic. It will receive the geofences to be monitored, register these geofences with CLLocationManager, and receive the event when it is triggered.

Initialize KSPGeofenceManager

KSPGeofenceManager is the entry point for all Geofence features in KSPLocationSDK. It needs to be initialized before using it.

1
2
3
4
5
6
7
8
9
10
11
12
{
…
    self.geofenceManager = [[KSPGeofenceManager alloc] init];
    self.geofenceManager.delegate = self;
 
    NSError* error;
    BOOL success = [self.geofenceManager startLocationService:&error];
    if(!success){
       // Handle the error here.
}
…
}

 

Implement KSPGeofenceManagerDelegate
1
2
3
4
5
6
7
8
9
- (void) geofenceManger:(KSPGeofenceManager *)manager didFailWithError:(NSError *)error
{
     // Handle the error here.
}
 
- (void) geofenceManger:(KSPGeofenceManager *)manager triggeredWithEvent:(KSPLocationEvent *)event
{
     // Handle the triggered event here.
}

 

Proximity

Initialize KSPBeaconManager

KSPBeaconManager is the entry point for all Proximity features in KSPLocationSDK. It needs to be initialized with the scanning mode before using it. There are 3 different modes: KSPBeaconGroupScanModeMonitoringGroup, KSPBeaconGroupScanModeRangingIndividuals or KSPBeaconGroupScanModeMix.

1
2
3
4
5
6
7
{
…
    self.beaconManager = [[KSPBeaconManager alloc] initWithMode:KSPBeaconGroupScanModeMix];
    self.beaconManager.delegate = self;
    [self.beaconManager startBeaconService];
…
}

 

Implement KSPBeaconManagerDelegate

In MonitoringGroup mode, you need to implement triggeredWithEvent which will be called when that iOS device has entered/exited a beacon group. In RangingIndividual mode, you need to implement didFoundBeacons which will report a list of beacons that is within proximity of the iOS device. In Mix mode, you will need to implement both.

1
2
3
4
5
6
7
8
9
10
11
12
13
14
- (void) beaconManager:(KSPBeaconManager *)manager didFailWithError:(NSError *)error
{
     // Handle the error here.
}
 
- (void) beaconManager:(KSPBeaconManager *)manager didFoundBeacons:(NSArray *)beacons
{
     // Handle the found beacons here.
}
 
- (void) beaconManager:(KSPBeaconManager *)manager triggeredWithEvent:(KSPLocationEvent *)event
{
     // Handle the triggered event here.    
}

Back To Top

Appendices

Appendix A

How to configure an iOS device to be an iBeacon:

    1. Run the Apsima Demo on that device
    2. Click on the last option (Configure Device as an iBeacon)

configure_device_iPhone

    1. Click on Enabled
    2. Locate the beacon you want to use from the dashboard.

proximity_tab_beacon

    1. Enter the Major ID and Minor ID values for that beacon.

configure_device_ids_iPhone

  1. Click Done and Save.
  2. Note: You must stay on this screen to keep use your device as an iBeacon.  Please make sure to turn off auto screen lock.