MOBILE SDK

# SDK integration

Apps basically need to be able to run location services in background with a working internet connection. Depending on the use case the SDK expects Bluetooth to be active. All communication with our servers is `JSON` and `HTTPS` and protected by an individual `API_TOKEN`.

We aim for continuous releases of our dashboard and the SDKs.

## Requirements

iOS

- The SDK requires the key `NSLocationAlwaysUsageDescription` to be present in the `.plist` file in order to register for location and iBeacon monitoring. 
- Since iOS 10 `NSBluetoothPeripheralUsageDescription` is also required in order to perform the check if Bluetooth is on/off
iBeacon monitoring does not require any additional permissions but Bluetooth must be active. The SDK does not require continuous location updates in background. 

- The SDK works on iOS 7.0 and up. It fails nicely on iOS 6.0. 

- Several iOS frameworks `CoreLocation.framework`, `CoreBluetooth.framework`, `CoreTelephony.framework`, `AdSupport.framework`, `SystemConfiguration.framework`

Android

- The SDK works on Android 4.4+
- Due to hardware compatibility issues we skip Beacon tracking on certain manufacturer/OS version combinations. 

- Permission requirements, most of them are optional: `INTERNET, BLUETOOTH, BLUETOOTH_ADMIN, ACCESS_WIFI_STATE, ACCESS_NETWORK_STATE, ACCESS_FINE_LOCATION`

- `Gson 2.2.4`

- Google Play Service 9.4.+. You can include parts of the library, Glimr SDK requires `compile 'com.google.android.gms:play-services-ads:9.4.+'` and `compile 'com.google.android.gms:play-services-location:9.4.+'`

 
KATConfiguration *config = [[KATConfiguration alloc] init];
config.apiToken = [[NSUUID alloc] initWithUUIDString:@"YOUR_API_TOKEN"];
config.askForLocationPermission = NO;
config.monitorVisits = YES;

KATBeaconManager *beaconManager = [[KATBeaconManager alloc] initWithConfiguration:config];
[beaconManager startCollecting];
[beaconManager debugWithHandler:^(id result) {
    NSLog(@"INTERNAL %@", result);
}];
   
KATAudienceManager *audienceManager = [[KATAudienceManager alloc] initWithApiToken:config.apiToken];
[audienceManager audiencesAndGeotagsWithCompletion:^(NSDictionary *audiences, NSError *error) {
  NSLog(@"AUDIENCES %@", audiences);
}];
// init the manager
KATManager manager = KATManager.getInstance();
manager.init(this.getApplicationContext(), "API_TOKEN", 30, false, 90);

// start monitoring for geofences and beacon ids configured on dashboard
KATManager.getInstance().startMonitoring(this);

// load tags for the current device
KATManager.getInstance().setAudiencesAndGeotagsCallback(new KATEvent() {
  @Override
  public void availableAudiencesUpdated(HashMap<String, ArrayList<String>> usertags) {
    // raw response
    Log.i("response", "availableAudiencesUpdated raw: " + usertags);

    // raw values
    Log.i("response", "availableAudiencesUpdated list: " + KATManager.mapToArrayList(usertags));

    // helper method to create a url query string from the mapping
    Log.i("response", "availableAudiencesUpdated query string: " + KATManager.map2QueryString(usertags));
  }
});

// load tags for the current device
KATManager.getInstance().getAudiencesAndGeotags();
let config = KATConfiguration()
config.apiToken = UUID(uuidString: YOUR_API_TOKEN)
config.suppressBluetoothAccuracyAlert = true
config.askForLocationPermission = true

let glimrManager = KATBeaconManager(configuration: config)!
glimrManager.startCollecting()

glimrManager.debug(handler: { (result) in
    print("DEBUG", result)
})
  
let audienceManager = KATAudienceManager(apiToken: UUID(uuidString: YOUR_API_TOKEN))
audienceManager?.audiences(completion: { (audiences, error) in
    print("AUDIENCES \(audiences)")
})
 

 iOS

You have two options to integrate the iOS SDK. You can find the latest release on [Github](https://github.com/KatalysatorAB/BeaconSDK-iOS/releases) or you use CocoaPods `pod "KatalysatorSDK"` to add the latest stable version to your app. For a Swift example check out this repository: https://github.com/KatalysatorAB/GlimrSDK-Swift

In order to listen to geo-fences and iBeacons you create a configuration object that you pass into the KATBeaconManager. 

To receive audience tags from the dashboard, all you need is to create an instance of the `KATAudienceManager` object with your API token and call `audiencesAndGeotagsWithCompletion`.

ANDROID

You find the library on [Github](https://github.com/KatalysatorAB/BeaconSDK-Android) as part of the sample implementation. 

Everything is managed by an `KATManager` instance and the `KATEvent` interface. Starting to monitor for regions is as simple as calling `startMonitoring` and receiving audience tags can be done by calling `getAudiencesAndGeotags`. 


ic_info_black_24dp_2x.png

API-Token

Replace `YOUR_API_TOKEN` with your API key.


ic_report_problem_black_24dp_2x.png

Caching

Please note that in order to feed our data fast enough into ad- and content-systems we have a multi layer cache within the SDK and on the dashboard side. It might take up to 60 minutes for changes to become active.


COLLECTING AUDIENCES

Region monitoring

 Configuration (iOS only)

Sample for a recommended `KATConfiguration` object


KATConfiguration *config = [[KATConfiguration alloc] init];
config.apiToken = [[NSUUID alloc] initWithUUIDString:@"YOUR_API_TOKEN"];
config.suppressBluetoothAccuracyAlert = YES;
KATManager manager = KATManager.getInstance();
manager.init(this.getApplicationContext(), "API_TOKEN", 30, false, 90);
let config = KATConfiguration()
config.apiToken = UUID(uuidString: "YOUR_API_TOKEN")
config.suppressBluetoothAccuracyAlert = true

 

The `KATConfiguration` object is necessary to initialise the region monitoring later on.

The options are:

Parameter | Default | Description
--------- | ------- | -----------
shareRegions | NO | If shareRegions is active the SDK will limit avoid clashes with regions set by other parts of the app
apiToken | nil | Your API token, required for any dashboard interaction
askForLocationPermission | YES | Decide if the SDK may ask for location permission
KATConfiguration.disableCaching | NO | Disables caching for development purposes
monitorVisits | NO | Enables visits tracking on iOS

Calling the provided method signature `- (NSArray *)configUpdate:(BOOL)force coordinate:(CLLocationCoordinate2D)coordinate completion:(KATUpdateConfigHandler)completion;` manually is not recommended as it will be called anyway when initialising the `KATBeaconManager`.
This method will update the local configuration.

Geo-fences and iBeacons

To initialise region monitoring all you need to do is to implement the sample code to the right.
Make sure this code is executed every time the app is started.
Calling it every time the app comes to foreground is fine as well.

KATConfiguration *config = [[KATConfiguration alloc] init];
config.apiToken = [[NSUUID alloc] initWithUUIDString:@"YOUR_API_TOKEN"];

KATBeaconManager *beaconManager = [[KATBeaconManager alloc] initWithConfiguration:config];
[beaconManager startCollecting];
// init the manager
KATManager manager = KATManager.getInstance();
manager.init(this.getApplicationContext(), "API_TOKEN", 30, false, 90);

// start monitoring for geofences and beacon ids configured on dashboard
KATManager.getInstance().startMonitoring(this);
let config = KATConfiguration()
config.apiToken = UUID(uuidString: "YOUR_API_TOKEN")
config.suppressBluetoothAccuracyAlert = true
config.askForLocationPermission = true

let glimrManager = KATBeaconManager(configuration: config)!
glimrManager.startCollecting()

 

Based on the dashboard configuration the callback will receive the response for a configured campaign.
The app can use this information further and present views, track events or perform other actions.

### Android

## URL Tracking

Since SDK version 1.7.6 iOS and 1.8.0 on Android apps have to possibility to track URLs/actions inside their applications. Those events will be used to improve the quality of the audience segments. I.e. a news application could track the article read by a user to further help defining the user's offline interests:

Sample web view url tracking: `trackURL`

- (BOOL)webView:(UIWebView *)webView shouldStartLoadWithRequest:(NSURLRequest *)request navigationType:(UIWebViewNavigationType)navigationType
{
    [KATAudienceManager trackURL:request.URL];
    return YES;
}
KATManager manager = KATManager.getInstance();
manager.init(this.getApplicationContext(), "API_TOKEN", 30, false, 90);
KATManager.getInstance().trackURL("url to track");

 

 Debugging (iOS only)

The SDK provides a few tweaks to help developer debug the SDK integration.

`triggerWithHandler` will perform a callback immediately before contacting the Glimr servers showing the payload that will be send to the dashboard.

Sample `triggerWithHandler`

[beaconManager triggerWithHandler:^(NSDictionary *requestDict)
{
  NSLog(@"TRIGGER %@", requestDict);
}];
// no additional logging for Android at this point, logs written to standard log
glimrManager.trigger { (result) in
    print("TRIGGER", result)
}

 

Sample `debugWithHandler`

`debugWithHandler` allows logging of different events that happen under the hood of the SDK.

[beaconManager debugWithHandler:^(id result)
{
  NSLog(@"DEBUG %@", result);
}];
// no additional logging for Android at this point, logs written to standard log
glimrManager.debug(handler: { (result) in
    print("DEBUG", result)
})

 

Those methods are completely optional and usually for debugging purposes only.

Audiences

Another functionality of the SDK is to collect additional data and read the assigned audience tags defined on the Glimr dashboard.
The dashboard allows to create audiences based on offline behaviour of a device gathered from iBeacon regions and geo-fences.
Applications can use the result of the mined data and use it i.e. to feed ad systems with additional keywords about the deivce/user.


 

RECEIVE AUDIENCES

 Get audience tags

The SDK allows developers to receive the tags assigned to a device. The example shows a full example of that. In general this function should be called whenever the app comes to foreground in order to receive the latest tags for a device.

### iOS
The completion block contains a `NSDictionary` wit the key `tags`, which represents an array of assigned tags for the device.

### Android
The interface method `availableAudiencesUpdated()` gets called with a HashMap representing the assigned tags.

Full example for reading tags assigned to the current device

KATAudienceManager *audienceManager = [[KATAudienceManager alloc] initWithApiToken:@"YOUR_API_TOKEN"];
[audienceManager audiencesAndGeotagsWithCompletion:^(NSDictionary *audiences, NSError *error)
{
  NSLog(@"AUDIENCES %@", audiences);
}];
// init the manager
KATManager manager = KATManager.getInstance();
manager.init(this.getApplicationContext(), "API_TOKEN", 30, false, 90);

// load tags for the current device
KATManager.getInstance().setAudiencesAndGeotagsCallback(new KATEvent() {
  @Override
  public void availableAudiencesUpdated(HashMap<String, ArrayList<String>> usertags) {
    // raw response
    Log.i("response", "availableAudiencesUpdated raw: " + usertags);

    // raw values
    Log.i("response", "availableAudiencesUpdated list: " + KATManager.mapToArrayList(usertags));

    // helper method to create a url query string from the mapping
    Log.i("response", "availableAudiencesUpdated query string: " + KATManager.map2QueryString(usertags));
  }
});
KATManager.getInstance().getAudiencesAndGeotags();
let audienceManager = KATAudienceManager(apiToken: UUID(uuidString: "YOUR_API_TOKEN"))
audienceManager?.audiences(completion: { (audiences, error) in
    print("AUDIENCES \(audiences)")
})