SDK Documentation

BehavioMobile
Document version 2.4.0
Android SDK version 1.5.0
iOS SDK version 1.3
Legal Notice
Copyright (C) 2011-2013 Behaviometrics AB

All Rights Reserved.

NOTICE: All information contained herein is, and remains the property of Behaviometrics AB.

Dissemination of this information or reproduction of this material is strictly forbidden unless

prior written permission is obtained from Behaviometrics AB.

Behaviometrics, Behavio and BehavioWeb are trademarks or registered trademarks of

Behaviometrics AB. All rights to these marks are reserved. Other names may be trademarks of
their respective owners.
Table of contents
SDK Documentation .....................................................................................................................................................1
BehavioMobile ................................................................................................................................................................1
Legal Notice ..........................................................................................................................................................................2
1 BehavioMobile SDK .................................................................................................................................................4
1.1 SDK DOs and DONTs.....................................................................................................................................4
1.2 Example System overview ..........................................................................................................................5
1.2.1 Code example part ................................................................................................................................5
2 Android Example integration: .............................................................................................................................6
2.1 XML .......................................................................................................................................................................6
2.2 Adding Key Down ...........................................................................................................................................6
2.3 Init of fieldnames ............................................................................................................................................7
2.4 Retrieving Timings data ...............................................................................................................................7
2.5 Clear fields and timings data ......................................................................................................................8
2.6 Custom data ......................................................................................................................................................8
2.7 Debug ................................................................................................................................................................ 10
3 iOS Example integration: .................................................................................................................................... 11
4 Links............................................................................................................................................................................ 12
4.1 Android Library ............................................................................................................................................ 12
4.2 Android Code Example .............................................................................................................................. 12
4.3 iOS Library ...................................................................................................................................................... 12
4.4 iOS Code Example ........................................................................................................................................ 12
4.5 BehavioWeb - POST Server...................................................................................................................... 13
4.6 BehavioWeb - Web Service ...................................................................................................................... 13
4.7 Demo Dashboard ......................................................................................................................................... 13
5 Support ...................................................................................................................................................................... 14
5.1 Limitations...................................................................................................................................................... 14
5.2 Release Notes ................................................................................................................................................ 14
5.2.1 Document .............................................................................................................................................. 14
5.2.2 Android................................................................................................................................................... 14
5.2.3 iOS............................................................................................................................................................. 15
1 BehavioMobile SDK
The BehavioMobile SDK enables an easy to use interface for gathering behavior timings from
editable text fields on the Android and Apple iOS systems. The behavior is captured by the SDK
and is retrieved as a JSON formatted string that can be sent to a BehavioWeb server for
evaluation.

Android BehavioMobile SDK uses edit text fields that are extensions of Android EditText fields.
While the iOS (iPhone / iPad) SDK utilizes listeners that can be hooked onto any textfield.

The fields can either gather the timings as they are or anonymously. Anonymous timings do not
store any key character information, which makes them suitable for password fields. However
anonymous timings give a slightly lower confidence due to less entropy used to analyze at a
BehavioWeb server.

1.1 SDK DOs and DONTs

The SDK does gather behavior timings data and format it to the correct JSON format, ready to be
analyzed by the BehavioWeb server.

The SDK does not send, analyze or score the behavior. BehavioWeb or a Behavio SDK, which
includes BehavioSecs machine learning algorithms, carries out this function.

Complete code examples for both the iOS and Android system can be found in section 4, as well
as the libraries (Android and iOS SDKs).
1.2 Example System overview

SDK
Gather timings

HTTP /
POST Timings/ID
Timings BehavioWeb
Customer
JSON
RISK
Engine
Score/Report

Optional Demo result

Used in SDK code example

Figure 1

Figure 1 shows how the SDK gathers data, note that the app using the BehavioMobile SDK needs
to send the timings received by the SDK as HTTP / POST to a risk engine server (see code
sample, chapter 4.2), which can contact the BehavioWeb web service interface to get a
score/report back. One can also by a direct call to the web service get a report from the
transaction, more info in chapter 4.6.

1.2.1 Code example part

Our demo server simulates a simple risk engine by forwarding the HTTPS posted timings to a
BehavioWeb server for analysis and returns a html page that the android app can display,
showing the result of the behavior analysis.
2 Android Example integration:
First step would be to add at least one Behavio EditText field to an Android layout.xml. That is
BehavioEditText and/or BehavioAnonomyousEditText, (this is not needed for custom fields, as in
chapter 2.6).

2.1 XML
<?xml version="1.0" encoding="utf-8"?>
<LinearLayout xmlns:android="http://schemas.android.com/apk/res/android"
android:orientation="vertical" android:layout_width="fill_parent"
android:layout_height="fill_parent">
<com.behaviosec.mobilesdk.BehavioEditText
android:layout_width="fill_parent" android:id="@+id/editTextUsername"
android:inputType="text" android:layout_marginLeft="10dp"
android:layout_height="wrap_content" android:layout_marginTop="20dp"
android:hint="Username" android:layout_marginRight="10dp" />
<com.behaviosec.mobilesdk.BehavioEditText
android:layout_width="fill_parent" android:id="@+id/editTextEmail"
android:inputType="textEmailAddress" android:layout_marginLeft="10dp"
android:layout_height="wrap_content" android:layout_marginTop="20dp"
android:hint="Email" android:layout_marginRight="10dp" />
<com.behaviosec.mobilesdk.BehavioAnonymousEditText
android:layout_width="fill_parent" android:id="@+id/editTextPassword"
android:inputType="textPassword" android:layout_marginLeft="10dp"
android:layout_height="wrap_content" android:layout_marginTop="20dp"
android:hint="Password" android:layout_marginRight="10dp" />
</LinearLayout>

The Behavio Edit Text fields extend Android EditText and share the same XML tags. This
example utilizes three edit fields: username, email and password. The password field is a
BehavioAnonomyousEditText field, and it is anonymized, it is best used for password fields and
needs to be static, i.e. no free text, (same every time).

2.2 Adding Key Down

It is important to extend the BehavioAbstractActivity to properly gather both up and down
timings from edit text fields.

public class AndroidActivity extends BehavioAbstractActivity

IMPORTANT: The class needs permission for an OVERLAY WINDOW that can catch down events
on the android soft keyboard:

Add the following line to AndroidManifest.xml: <uses-permission

android:name="android.permission.SYSTEM_ALERT_WINDOW"></uses-permission>

The abstract class has one abstract method that needs to be implemented, initActivity(). This
methods should contain the initiation of any Behavio Edit Text fields.
2.3 Init of fieldnames
Each field needs a unique ID that is associated with the field, this should be set as soon as the
fields are created. Note that the fields are created and initiated inside the initActivity() method.
Not inside the onCreate() of the activity. Also note that setContentView(R.layout.main); is called
from the initActivity() method, (otherwise are the edit text fields null, and the result is a null
pointer exception).

protected BehavioEditText editTextUsername;

protected BehavioEditText editTextEmail;
protected BehavioAnonymousEditText editTextPassword;

public void initActivity() {

setContentView(R.layout.main);

// Init Edit Views

editTextUsername = (BehavioEditText) this
.findViewById(R.id.editTextUsername);
editTextEmail = (BehavioEditText) this
.findViewById(R.id.editTextEmail);
editTextPassword = (BehavioAnonymousEditText) this
.findViewById(R.id.editTextPassword);

// The field name also acts as ID for that particular field, used to
// identify what field to analyze on Behavio server
editTextUsername.setFieldName("text#username");
editTextEmail.setFieldName("text#email");
editTextPassword.setFieldName("password#password");
}

2.4 Retrieving Timings data

The data is hold by a static class BehavioTimings, it is updated each time a user types in any
Behavio Field. To retrieve data, access the method:

String timings = BehavioTimings.getTimingsAsJSONString();

This should be retrieved and sent to the server when the fields are completely filled by the user.
For example after user has inputted username and password and pressed submit.
2.5 Clear fields and timings data
It is not sufficient to only erase the text fields by setting the text to "". The timings data also
needs to be cleared for new input. Use either .clearText method on each Behavio edit field or the
BehavioTimings.clearALL(), to clear all Behavio fields. Used when user submits or hits a clear
button.

// Clear each field

editTextUsername.clearText();
editTextPassword.clearText()

// Or all fields at once

BehavioTimings.clearAll();

2.6 Custom data

It is possible to send extra data, either as behavior or extra info from the device, when custom
objects are timed.

If buttons are used as inputs without any behavior edit text to capture timings, it is still possible
to gather behavior, if the buttons are timed.

Example: An application has ten touch buttons 0-9. The buttons are used to enter a five-digit
number. To get timings from this application one would add a 'touch' listener to get down
timings and a 'clicked' listener to get up timings. A general JSONArray would store each down
and up timing.

A timing object holding one event looks like this: [type, key, time]. More info on JSON objects can
be found in the 'BehavioWeb Integration Guide.pdf' (see chapter 4.6). Code example below
shows how a custom behavior app could function.
// Global variables
JSONArray fiveDigitTimings = new JSONArray();
long startTime = System.currentTimeMillis();

...

// In a method, could be onCreate

// ButtonThree on touch (DOWN)

buttonThree.setOnTouchListener(new View.OnTouchListener() {
@Override
public boolean onTouch(View v, MotionEvent event) {

JSONArray tempDownTimings = new JSONArray();

long downTime = startTime- System.currentTimeMillis();

tempDownTimings.put(0); // add 0 for down

tempDownTimings.put(3); // Button three was pressed
tempDownTimings.put(downTime); // add Time
fiveDigitTimings.put(tempDownTimings); // Add to timings JSON

return false;
}
});

// ButtonThree on click (UP)

buttonThree.setOnClickListener(new View.OnClickListener() {
@Override
public void onClick(View v) {

JSONArray tempDownTimings = new JSONArray();

long upTime = startTime- System.currentTimeMillis();

tempUpTimings.put(1); // add 1 for up

tempUpTimings.put(3); // Button three was relesed
tempUpTimings.put(upTime); // add Time
fiveDigitTimings.put(tempUpTimings); // Add to timings JSON
}
});

// Method to send the gathered data

// Add custom data, retrive it as JSON String and post it

protected void sendDataFiveDigitData(){

BehavioTimings.addCustomJSONArrayTiming(
BehavioTimings.FIELD_TYPE_TEXT_ALPHANUM, "fiveDigitFieldName",
fiveDigitTimings); // Set field type, name and data

String data = BehavioTimings.getTimingsAsJSONString(); // Get behavior data

postDataToServer(data); // Post behavior data to server
}
2.7 Debug

// Import log bridge for debug text to ADB

import com.behaviosec.mobilesdk.LogBridge;

private void initLog(){

LogBridge.init(this);

(Consult support to get further help with any debugging)

3 iOS Example integration:
The header file describing the different calls to the SDK library.

#import <Foundation/Foundation.h>
#import <UIKit/UITextField.h>

@interface BehavioSec : NSObject

-(void)registerField:(UITextField *)field withName:(NSString *)name

isAnonymous:(BOOL)anonymous;
-(void)addInformationField:(NSString *)information withName:(NSString *)name;
-(void)setCurrentField:(UITextField *)textField;
-(void)registerButton:(UIButton *)button;
-(NSString *)getSummary;
-(void)resetTimes;
-(void)clear;

+(BehavioSec*) sharedInstance;

@end

Register a field to be monitored by BehavioMobile SDK

// Register field codeField to the Behaviosec library

[[ BehavioSec sharedInstance ] registerField:self.codeField withName:@"text#code"
isAnonymous:NO ] ;

// Clear(reset) timings
-(void)clear {
[ [ BehavioSec sharedInstance ] resetTimes ];
self.codeField.text = @"";
}

Get the timings data as JSON string.

NSString *result = [ [ BehavioSec sharedInstance ] getSummary];

One can also register custom buttons, when the built in soft-keyboard is not used.

[[ BehavioSec sharedInstance ] registerButton:self.key1 ];

It is also possible to add custom fields, for storing information regarding for example location
(GPS info) etc.

[[ BehavioSec sharedInstance ] addInformationField:@"just some text as an example" withName:@"information name

of that text" ];
4 Links
This section contains links to the SDKs, code examples and more.

4.1 Android Library

The Android library can be downloaded from the following link.

BehavioSec_Mobile_SDK_Android_1.5.0.zip

It includes the library and javadocs for calling it.

4.2 Android Code Example

A complete Eclipse code example utilizing the SDK can be downloaded below.

Behavio_SDK_Demonstration.3.0.zip

It uses two fields to gather timings data.

4.3 iOS Library

The iOS library can be downloaded from the following link.

BehavioSec_Mobile_SDK_iOS_1.2.zip

4.4 iOS Code Example

An iOS code example featuring custom buttons can be downloaded from the following location.
It features a PIN number pad example with custom keyboard.

BehavioSec_iOS_DemoPIN_1.2.zip

And below an iOS code example featuring native keyboard/pinpad can be downloaded.

BehavioSec_iOS_DemoNative_1.2.zip
4.5 BehavioWeb - POST Server
A test web server provided by BehavioSec may be used to test your implementation of any
software utilizing the BehavioMobile SDK.

Send in timings data using HTTP POST to the following address:

http://demo.behaviosec.com/BehavioWebDemo/getReport.jsf

URL = "http://demo.behaviosec.com/BehavioWebDemo/getReport.jsf";

ebView webviewResult = (WebView) resultDialog

.findViewById(R.id.webViewResults);

webviewResult.setWebChromeClient(new WebChromeClient());
webviewResult.setWebViewClient(new WebViewClient());
webviewResult.getSettings().setJavaScriptEnabled(true);

webviewResult.loadUrl(URL + "?id=" + java.net.URLEncoder.encode(id)

+ "&data=" + java.net.URLEncoder.encode(data));

Android example code to send user timings (data) and user ID (id) to the BehavioWeb Demo
server.

4.6 BehavioWeb - Web Service

It is possible to directly call the BehavioWeb web service using SOAP calls, the address to the
demo server wsdl is:

http://demo.behaviosec.com/BehavioWebService/BehavioWeb?wsdl

A full documentation on possible calls and usage of the web service can found here:

BehavioWeb Integration Guide.pdf

4.7 Demo Dashboard

Any successful calls, posts or submits to the dashboard may be traced at our demo dashboard:

http://demo.behaviosec.com:8080/BehavioWebDashboard/overview.jsf
5 Support
To get support regarding this product, write a mail to support@behaviosec.com with the subject
"Behavio Android Support" or "Behavio iOS Support".

5.1 Limitations

5.2 Release Notes

Release notes for Android, the document and iOS.

5.2.1 Document
Document 2.4.0

Rewritten parts about Android SDK, old chapter 2.2 and 2.4

Chapter 2.3 obsolete and removed. (Activity life-cycle).

Changed text in android debug chapter.

Document 2.3.6

Updated iOS SDK link to version 1.2

Added link to iOS demo for native keyboard/pinpad

Document 2.3.5

Fixed error declaring BehavioAnonymousEditText section 2.1.3

Added chapter 5.2.1 Activity Lifecycle

Fixed reference to sample code in chapter 1.2

Updated chapter numbering

Removed Limitations for Motorola phones, now fixed

Document 2.3.4

Added versioning

5.2.2 Android
Android 1.5.0

Added abstract class that handles life-cycle management as well as the key down listener
initiation.

Android 1.4.4
 Added lifecycle management

Added fix for Motorola phones on down timings

Added Debug version

Android 1.4.3

Added fix that removes empty fields from final JSON if no input was recorded

Added fix for down timings on first field on any screen

Invisible text view will be added if only one (focusable) field is configured

Updated links

5.2.3 iOS
iOS 1.2

Bug fix for native pinpad

iOS 1.3

Support for iOS6.x and iOS7.0

added API method to get SDK version number

added iOS and SDK version number in JSON