Ionic

Integrate the Colocator Cordova Plugin into your Ionic app

Adding the dependency

Install the plugin using CLI

$ ionic cordova plugin add com.crowdconnected.colocator.cordovaplugin

Integration Sample

Getting Permission

iOS Additional steps

Change the permission descriptors in info.plist file of your iOS project

  • Note that the plist items are already present in your info file after adding the plugin
<key>NSLocationAlwaysAndWhenInUseUsageDescription</key>
<string>YOUR_TEXT_GOES_HERE</string>
<key>NSLocationAlwaysUsageDescription</key>
<string>YOUR_TEXT_GOES_HERE</string>
<key>NSLocationWhenInUseUsageDescription</key>
<string>YOUR_TEXT_GOES_HERE</string>
<key>NSBluetoothPeripheralUsageDescription</key>
<string>YOUR_TEXT_GOES_HERE</string>

If you will use Colocator for Indoor Services, also change the following permission descriptors accordingly

<key>NSBluetoothAlwaysUsageDescription</key>
<string>YOUR_TEXT_GOES_HERE</string>
<key>NSMotionUsageDescription</key>
<string>YOUR_TEXT_GOES_HERE</string>

For more details about these permissions in the iOS section

Location Permission

Request location permission using Geolocation or other preferred method.

CLI:

$ ionic cordova plugin add cordova-plugin-geolocation
$ npm install @ionic-native/geolocation

TS file:

import { Geolocation } from '@ionic-native/geolocation/ngx';
...
constructor(public platform: Platform, private geolocation: Geolocation) {  
    this.platform.ready().then(() => {
      this.geolocation.getCurrentPosition();
    })
}

Bluetooth Permission - Used for Indoor Location Service

ColocatorWrapper.triggerBluetoothPermissionPopUp(YOUR_CALLBACK_FUNCTION, YOUR_ERROR_FUNCTION)

Motion Permission - Used for Indoor Location Service

ColocatorWrapper.triggerMotionPermissionPopUp(YOUR_CALLBACK_FUNCTION, YOUR_ERROR_FUNCTION)

Enabling Location Gathering

Start the library

Start the library when the application starts using:

declare var ColocatorWrapper: any;
...
ColocatorWrapper.start("YOUR_APP_KEY", YOUR_CALLBACK_FUNCTION, YOUR_ERROR_FUNCTION);

In iOS the library should be started in AppDelegate.m as follows:

#import <CCLocation/CCLocation-Swift.h>
...
- (BOOL)application:(UIApplication*)application didFinishLaunchingWithOptions:(NSDictionary*)launchOptions
{
    ...
    [CCLocation.sharedInstance startWithApiKey:@"YOUR_APP_KEY" urlString:@"URL_STRING"];
    ...
}

Background Refresh - only iOS

We use background refresh to periodically check whether we should enable location tracking.

Enable Background Refresh by registering for events in AppDelegate.m:

Import CCLocation Obj-C header

#import <CCLocation/CCLocation-Swift.h>

Set the minimum time interval for background refresh

[[UIApplication sharedApplication] setMinimumBackgroundFetchInterval:60];

Calling the library at background refresh

-(void)application:(UIApplication *)application performFetchWithCompletionHandler:(void (^)(UIBackgroundFetchResult))completionHandler {
    // At background refresh, the CCLocation library should be notified to update its state
    [CCLocation.sharedInstance updateLibraryBasedOnClientStatusWithClientKey:@"YOUR_APP_KEY" isSilentNotification:false completion:^(BOOL result) {}];
}

Silent Push Notifications - only iOS

We use Silent Push Notifications to enable location tracking at a given time.

Please enable Silent Push Notifications in AppDelegate.m by:

  1. Ensuring the app has notification permission
  2. Registering for remote notifications
[[UIApplication sharedApplication] registerForRemoteNotifications];
  1. Sending the APNS Token as an alias:
- (void)application:(UIApplication *)application didRegisterForRemoteNotificationsWithDeviceToken:(NSData *)deviceToken {
    // For CCLocation messaging feature, send device token to the library as an alias
    NSString * deviceTokenString = [[[[deviceToken description]
     stringByReplacingOccurrencesOfString: @"<" withString: @""]
     stringByReplacingOccurrencesOfString: @">" withString: @""]
     stringByReplacingOccurrencesOfString: @" " withString: @""];
    [CCLocation.sharedInstance addAliasWithKey:@"apns_user_id" value:deviceTokenString];
}
  1. Calling the library when one is received:
NSDictionary *apsInfo = [userInfo objectForKey:@"apsInfo"];
NSString *source = [apsInfo objectForKey:@"source"];
if ([source isEqualToString:@"colcoator"]) {
    [CCLocation.sharedInstance receivedSilentNotificationWithUserInfo:userInfo clientKey:@"YOUR_APP_KEY" completion:^(BOOL result) {}];
}

Disabling Location Gathering

If required you can stop the library in your TS file

ColocatorWrapper.stop(YOUR_CALLBACK_FUNCTION, YOUR_ERROR_FUNCTION);

Sending an Alias

Aliases are key-value pairs. They are primarily used to send alternative IDs for a device, for example a unique Push Notification identifier. Go to the Push Notification Integrations page for more details

ColocatorWrapper.addAlias("YOUR_KEY", "YOUR_VALUE", YOUR_CALLBACK_FUNCTION, YOUR_ERROR_FUNCTION);

Indoor Location Service

For indoor location and positioning, a few more steps need to be implemented

Location Callbacks - Only for Indoor Navigation Purposes

The latest location can be sent back to the device either as a one-off or a stream of updates. This is primarily used for displaying the location of the device on a map.

The location update callbacks contain a JSON object.

Request one location:

ColocatorWrapper.requestLocation(YOUR_CALLBACK_FUNCTION, YOUR_ERROR_FUNCTION)

Request a stream of location updates:

ColocatorWrapper.registerLocationListener(YOUR_CALLBACK_FUNCTION, YOUR_ERROR_FUNCTION)

LocationResponse object contains the field “floor” starting with v2.7.0

Stopping Location Updates

Please make sure you unregister from location callbacks when the user is not using the indoor map screen or navigation.

This is important for battery and performance optimization.

Stop the stream of updates:

ColocatorWrapper.unregisterLocationListener(YOUR_CALLBACK_FUNCTION, YOUR_ERROR_FUNCTION)