Pass

Programming Guide

Version 1.2.2

Copyright © Samsung Electronics Co., Ltd. All rights reserved. Page 1

Table of Contents
1. Overview ............................................................................................................................................................ 3

2. Architecture ........................................................................................................................................................ 4

2.1. Classes and Interfaces ....................................................................................................................................... 5

2.2. Supported Platforms ......................................................................................................................................... 5
2.3. Supported Features ........................................................................................................................................... 5
2.4. Components ...................................................................................................................................................... 6
2.5. Installing the Package for Eclipse ...................................................................................................................... 7

3. Hello Pass ................................................................................................................................................................ 8

4. Using the Spass Class ............................................................................................................................................. 10

4.1. Using the initialize() Method ........................................................................................................................... 10

4.2. Handling SsdkUnsupportedException ............................................................................................................. 11
4.3. Checking the Availability of Pass Package Features ........................................................................................ 11

5. Using the Pass Package .......................................................................................................................................... 12

5.1. Checking for Registered Fingerprints on the Device ....................................................................................... 12

5.2. Requesting Fingerprint Recognition ............................................................................................................... 13
5.3. Cancelling Fingerprint Recognition ................................................................................................................. 14
5.4. Registering Fingerprints .................................................................................................................................. 14
5.5. Getting the Fingerprint Index upon Recognition Success ............................................................................... 15
5.6. Getting the Registered Fingerprint Index and Name ...................................................................................... 15
5.7. Getting the Registered Fingerprint Index and unique ID ................................................................................ 15
5.8. Specifying an Index for Fingerprint Recognition ............................................................................................. 15
5.9. Adding a title to the UI .................................................................................................................................... 16
5.10. Adding a Logo to the UI ................................................................................................................................... 16
5.11. Setting the Transparency in Background elements ......................................................................................... 17
5.12. Setting Dialog Behavior when Background Elements are Touched ................................................................ 17
5.13. Broadcast actions when registered fingerprint is changed. ............................................................................ 18
5.14. Getting the guide when fingerprint recognition is failed due to the poor quality. ......................................... 19
5.15. Adding a button to the UI ................................................................................................................................ 19
5.16. Changing a standby string to the UI ................................................................................................................ 20

Copyright .................................................................................................................................................................. 22

Copyright © Samsung Electronics Co., Ltd. All rights reserved. Page 2

 1. Overview
Pass allows you to use fingerprint recognition in your application to identify users whose fingerprints have
been registered in the device.

You can use Pass to:

 provide better application security

 increase the convenience of the user identification process

Copyright © Samsung Electronics Co., Ltd. All rights reserved. Page 3

 2. Architecture
Figure 1 shows the Pass architecture.

Figure 1: Pass architecture

The architecture consists of:

 Applications: one or more applications that use Pass

 Pass: components for initializing the Pass package
 Fingerprint Manager Service: service component for fingerprint recognition, registration, and
deletion
 Fingerprint Manager: proxy component for the Fingerprint Manager Service

Copyright © Samsung Electronics Co., Ltd. All rights reserved. Page 4

2.1. Classes and Interfaces
The Pass classes and interfaces that you can use in your application include:

 Spass: initializes the Pass package

 SpassFingerprint: manages fingerprint recognition
 IdentifyListener: listens for fingerprint recognition events
 RegisterListener: listens for fingerprint registration events

2.2. Supported Platforms

Android 4.2 (Jelly Bean API 17) or above that supports Pass.

2.3. Supported Features

Pass supports the following features:

 recognize fingerprints
 cancel recognition requests
 check whether a registered fingerprint exists on the device
 register fingerprints through the Enroll screens of the Setting menu
 get fingerprint index upon recognition success
 get list of names and indexes of registered fingerprints
 get list of names or unique IDs of registered fingerprints with their indexes
 specify an index for fingerprint recognition
 add title to the user interface
 add logo to the user interface
 set the transparency of background elements
 set dialog behavior when background elements are touched
 broadcasts from the device when registered fingerprint is changed
 get the guide for the poor quality
 set the button for the user interface
 change the standby string for the user interface

Copyright © Samsung Electronics Co., Ltd. All rights reserved. Page 5

2.4. Components
 Components
o [Link]
 Imported packages:
o [Link]

Copyright © Samsung Electronics Co., Ltd. All rights reserved. Page 6

2.5. Installing the Package for Eclipse
To install Pass for Eclipse:

1. Add the [Link] file to the libs folder in Eclipse.

Figure 2: libs folder in Eclipse

The following permission has to be specified in the [Link] file to initialize Pass.

<uses-permission android:name=
"[Link].WRITE_USE_APP_FEATURE_SURVEY"/>

If you did not add the permission,

o Android 4.4.2 (KitKat) and above: SecurityException is thrown and your application will not work.
o Prior to Android 4.4.2 (KitKat): no exception and the application will work properly.

Copyright © Samsung Electronics Co., Ltd. All rights reserved. Page 7

 3. Hello Pass
Hello Pass is a simple program that:

 initializes the Spass class

 requests for fingerprint recognition

 receives fingerprint recognition events from the registered listener
public class HelloPass extends Activity {

private SpassFingerprint mSpassFingerprint;

private Context mContext;

private [Link] listener =

new [Link]() {

@Override
public void onFinished(int eventStatus) {
// It is called when fingerprint identification is finished.
if (eventStatus == SpassFingerprint.STATUS_AUTHENTIFICATION_SUCCESS) {
// Identify operation succeeded with fingerprint

} else if (eventStatus == SpassFingerprint.

STATUS_AUTHENTIFICATION_PASSWORD_SUCCESS) {
// Identify operation succeeded with alternative password
}
else {
// Identify operation failed with given eventStatus.
// STATUS_TIMEOUT_FAILED
// STATUS_USER_CANCELLED
// STATUS_AUTHENTIFICATION_FAILED
// STATUS_QUALITY_FAILED
// STATUS_USER_CANCELLED_BY_TOUCH_OUTSIDE
// STATUS_BUTTON_PRESSED
// STATUS_OPERATION_DENIED
}
}

@Override
public void onReady() {
// It is called when fingerprint identification is ready after
// startIdentify() is called.
}

@Override
public void onStarted() {

Copyright © Samsung Electronics Co., Ltd. All rights reserved. Page 8

 // It is called when the user touches the fingerprint sensor after
// startIdentify() is called.
}
@Override
public void onCompleted() {
//It is called when identify request is completed.
}
};

@Override
protected void onCreate(Bundle savedInstanceState) {
[Link](savedInstanceState);
setContentView([Link].activity_main);

mContext = this;
mSpass = new Spass();

try {
[Link]([Link]);
} catch (SsdkUnsupportedException e) {
// Error handling
} catch (UnsupportedOperationException e){
// Error handling
}
isFeatureEnabled = [Link](Spass.DEVICE_FINGERPRINT);

if(isFeatureEnabled){
mSpassFingerprint = new SpassFingerprint([Link]);
} else {
log("Fingerprint Service is not supported in the device.");
}
}

Copyright © Samsung Electronics Co., Ltd. All rights reserved. Page 9

 4. Using the Spass Class
The Spass class provides the following methods:

 initialize(): initializes Pass

 getVersionCode(): gets the Pass version number as an integer

 getVersionName(): gets the Pass version name as a string

 isFeatureEnabled(): checks if a Pass package feature is available on the device

Spass spass = new Spass();

try {
[Link](mContext);
} catch (SsdkUnsupportedException e) {
// Error handling
}

int versionCode = [Link]();

String versionName = [Link]();

4.1. Using the initialize() Method

The [Link]() method:

 initializes the Pass package

 checks if the device is a Samsung device
 checks if the device supports the Pass package
 checks if the Pass package libraries are installed on the device

void initialize(Context context) throws SsdkUnsupportedException

Initializing should be implemented just once before accessing SpassFingerprint class. If the Pass package
fails to initialize or if the device does not support Pass, the initialize() method throws an
SsdkUnsupportedException exception. To find out the reason for the exception, you can check it through
the exception message.

Copyright © Samsung Electronics Co., Ltd. All rights reserved. Page 10

4.2. Handling SsdkUnsupportedException
If an SsdkUnsupportedException exception is thrown, you can get the exception message type using
[Link]().

4.3. Checking the Availability of Pass Package Features

You can check if a Pass package feature is supported on the device with the isFeatureEnabled() method.
Pass the feature type as a parameter when calling the isFeatureEnabled() method. The following
feature types are defined in the Spass class:

 DEVICE_FINGERPRINT: indicates if the device supports the default identification requests and the
user interface
 DEVICE_FINGERPRINT_FINGER_INDEX: indicates if the API allows you to set a specified fingerprint
using its index for fingerprint recognition
 DEVICE_FINGERPRINT_CUSTOMIZED_DIALOG: indicates the API for defining a custom user interface

 DEVICE_FINGERPRINT_UNIQUE_ID: indicates the API for getting index and fingerprint unique IDs

 DEVICE_FINGERPRINT_AVAILABLE_PASSWORD: indicates if the device supports the backup Password

of fingerprint

The isFeatureEnabled() method returns a Boolean value that indicates the support for the feature on
the device.
boolean isFeatureEnabled(int type)

Copyright © Samsung Electronics Co., Ltd. All rights reserved. Page 11

 5. Using the Pass Package
The SpassFingerprint class provides the following methods for fingerprint recognition:

 startIdentify(): requests the identification operation to recognize a fingerprint without a user

interface
 startIdentifyWithDialog(): requests the identification operation to recognize a fingerprint
with a user interface
 hasRegisteredFinger(): checks whether there are any registered fingerprints on the device

 cancelIdentify(): cancels the identification operation

 registerFinger(): registers a fingerprint on the device through the Enroll screen of the Setting
menu
 getIdentifiedFingerprintIndex():obtains the fingerprint index of the identified
fingerprint when recognition is a success
 getRegisteredFingerprintName(): obtains a list of registered fingerprint
indexes and names in the Settings menu
 setIntendedFingerprintIndex(): specifies a fingerprint index for identification
before requesting fingerprint recognition
 setDialogTitle() : adds a title in the user interface before requesting fingerprint recognition

 setDialogIcon() : adds a logo in the bottom left portion of the UI before requesting fingerprint
recognition
 setDialogBgTransparency() : sets the transparency of background elements before requesting
fingerprint recognition
 setCanceledOnTouchOutside() : sets a value that determines whether the user interface is
dismissed or not when touching background elements before requesting fingerprint recognition
 getGuideForPoorQuaility() : obtains the string of guide when recognition is failed due to the poor quality.
 setDialogButton() : adds the button in the user interface for connecting own menu after the user interface is
dismissed.
 changeStandbyString() : changes the standby string as own in the user interface.

5.1. Checking for Registered Fingerprints on the Device

To check whether a registered fingerprint for the current user exists on the device, call
hasRegisteredFinger().

The method returns true if a registered fingerprint exists on the device and returns false if no registered
fingerprint is found.

boolean mHasRegisteredFinger = [Link]();

Copyright © Samsung Electronics Co., Ltd. All rights reserved. Page 12

5.2. Requesting Fingerprint Recognition
To request an identification operation to recognize a fingerprint without a user interface (UI), call
startIdentify(). Before calling this method, initialize an IdentifyListener which provides the following
events:

 onReady(): called when the fingerprint sensor is in the ready state

 onStarted(): called when the user touches the fingerprint sensor and starts to swipe their finger

 onFinished(): called when the identify operation is completed.

 onCompleted() : called when the identify request is completed.

To request the identify operation with a UI, call startIdentifyWithDialog().

If your application uses the identify operation with a UI, you should check if the device supports backup
password after calling [Link](Spass.DEVICE_FINGERPRINT_AVAILABLE_PASSWORD)
first and if the device supports it, you have the additional option of using a password instead of a
fingerprint for identification. To show the Password button on the UI, set enablePassword to true. To hide
the button and use only fingerprint identification, set enablePassword to false.

Both startIdentify () and startIdentifyWithDialog () methods follow the policy of device fingerprint
recognition. So the operation is different depending on each device.

In some devices, fingerprint recognition is denied after 5 failed attempts. Afterwards, only password
verification requests will be allowed with unlimited attempts in the device which support the backup
password. However, an SpassInvalidStateException occurs per request if a timer is introduced for
lockout.

When the identify operation is requested, the fingerprint sensor enters the Ready state. When the
startIdentify() or startIdentifyWithDialog() operations are finished, the onFinished() method of
IdentifyListener is called and passes the event status that allows you to verify the result of the identify
operation:

 If there is no activity for 20 seconds after the fingerprint sensor enters the Ready state, the request
is canceled, and the onFinished() method is called with the event status,
STATUS_TIMEOUT_FAILED.

 If the device is support backup password and the backup password matches, the event status is
STATUS_AUTHENTIFICATION_PASSWORD_SUCCESS.

 If the request of identify is accepted and then identify operation is failed and a timer is started for
lockout, the onFinished() method is called with the event status,
STATUS_AUTHENTIFICATION_FAILED and STATUS_OPERATION_DENIED
 If the fingerprint recognition fails, the following event status defines the reason for the failure:
o STATUS_USER_CANCELLED
o STATUS_QUALITY_FAILED
o STATUS_SENSOR_FAILED

Copyright © Samsung Electronics Co., Ltd. All rights reserved. Page 13

 o STATUS_USER_CANCELLED_BY_TOUCH_OUTSIDE
o STATUS_AUTHENTIFICATION_FAILED
STATUS_BUTTON_PRESSED
[Link]([Link], listener, false);

private [Link] listener =

new [Link]() {
@Override
public void onFinished(int eventStatus) {
// It is called when fingerprint identification is finished.
}

@Override
public void onReady() {
// It is called when fingerprint identification is ready after
// startIdentify() is called.
}

@Override
public void onStarted() {
// It is called when the user touches the fingerprint sensor after
// startIdentify() is called.
}
@Override
public void onCompleted() {
//It is called when identify request is completed
}

};

5.3. Cancelling Fingerprint Recognition

To cancel the fingerprint recognition request that started the identify operation through startIdentify()
or startIdentifyWithDialog(), call cancelIdentify().

[Link]();

5.4. Registering Fingerprints

If there are no registered fingerprints on the device, you can directly access the Settings menu to register
fingerprints by calling registerFinger(). Before calling this method, initialize a RegisterListener. To return
to the previous screen after the fingerprint registration completes, call onFinished() of RegisterListener.

[Link](this, mRegisterListener);

Copyright © Samsung Electronics Co., Ltd. All rights reserved. Page 14

 private [Link] mRegisterListener = new
[Link]() {

@Override
public void onFinished() {
log("[Link]()");

}
};

5.5. Getting the Fingerprint Index upon Recognition Success

After fingerprint recognition is finished, you can get the fingerprint index of the identified fingerprint. This
API must be called inside [Link]() in order for it to return the fingerprint index. Otherwise,
it returns -1 to indicate an invalid value. If the user authenticates using a password, the API returns 0.

[Link]();

private [Link] listener =

new [Link]() {
@Override
public void onFinished(int eventStatus) {
int FingerprintIndex = [Link]();
// It is called when fingerprint identification is finished.
}

5.6. Getting the Registered Fingerprint Index and Name

Use the method below to return a list of indexes and names of registered fingerprints in the Settings menu.

[Link] ();

5.7. Getting the Registered Fingerprint Index and unique ID

The following code returns a list of indexes and unique IDs of registered fingerprints in the Settings menu if
isFeatureEnabled(Spass.DEVICE_FINGERPRINT_UNIQUE_ID) returns true.

if ([Link](Spass.DEVICE_FINGERPRINT_UNIQUE_ID)){
mSpassFingerprint. getRegisteredFingerprintUniqueID ()
}

Copyright © Samsung Electronics Co., Ltd. All rights reserved. Page 15

5.8. Specifying an Index for Fingerprint Recognition
You can specify a fingerprint index for identification before requesting the fingerprint recognition by calling
the setIntendedFingerprintIndex() method of the SpassFingerprint class if
isFeatureEnabled(Spass.DEVICE_FINGERPRINT_FINGER_INDEX) returns true.

If the parameter to this method is set as null or no index, then the function finds a match against all
registered fingerprints. If the parameter to this method is a valid index, then the function finds a match
against the designated fingerprint.

[Link](ArrayList<Integer>);
ArrayList<Integer> designatedFingers = new ArrayList<Integer>();
[Link](2);
[Link](3);

if ([Link](Spass.DEVICE_FINGERPRINT_FINGER_INDEX)){
mSpassFingerprint. setIntendedFingerprintIndex (designatedFingers);
}
[Link]([Link],listener, true);

private [Link] listener =

new [Link]() {
...

5.9. Adding a title to the UI

This feature allows you to add the customized title on top of the UI before requesting fingerprint
recognition.

If isFeatureEnabled(Spass. DEVICE_FINGERPRINT_CUSTOMIZED_DIALOG) returns true, then this

function can be activated.

Calling the setDialogTitle() method from the SpassFingerprint class allows you to set a string as a
custom title. If the string is null, then the title would not be displayed in the UI.

[Link](String titleText, int titleColor);

if([Link](Spass.DEVICE_FINGERPRINT_CUSTOMIZED_DIALOG)){
[Link]("Customized Dialog", 0xff0000);
}
[Link]([Link],listener, true);

private [Link] listener =

new [Link]() {
...

Copyright © Samsung Electronics Co., Ltd. All rights reserved. Page 16

5.10. Adding a Logo to the UI
This feature allows you to add a customized Logo on the bottom left corner of the UI before requesting
fingerprint recognition. You can use the setDialogIcon() method of the SpassFingerprint class, if
isFeatureEnabled (Spass. DEVICE_FINGERPRINT_CUSTOMIZED_DIALOG) returns true.

The parameter of the function accepts a file name which is stored in /res/Drawable/… of the device. If the
parameter is set to null or the image cannot be found, then the method displays the default dialog without
the icon.

[Link](String iconName);

if([Link](Spass.DEVICE_FINGERPRINT_CUSTOMIZED_DIALOG)){
[Link]("ic_launcher");
}
[Link]([Link],listener, true);

private [Link] listener =

new [Link]() {
...

5.11. Setting the Transparency in Background elements

This feature allows you to set the transparency of background elements when the user interface is active
before requesting fingerprint recognition. Since this is a custom UI feature, isFeatureEnabled(Spass.
DEVICE_FINGERPRINT_CUSTOMIZED_DIALOG) must return true to use this feature.

If there is no value assigned to the setDialogBgTransparency() method of the SPassFingerprint class,

then the method assumes default transparency.

[Link](int transparency);

if([Link](Spass.DEVICE_FINGERPRINT_CUSTOMIZED_DIALOG)){
[Link](0);
}
[Link]([Link],listener, true);

private [Link] listener =

new [Link]() {
...

Copyright © Samsung Electronics Co., Ltd. All rights reserved. Page 17

5.12. Setting Dialog Behavior when Background Elements
are Touched
This feature allows you to set whether the UI is dismissed or not when touching background elements. The
setCanceledOnTouchOutside() method from the SPassFingerprint class accepts a boolean value and this
must be set before requesting fingerprint recognition in order for it to work. This also requires
isFeatureEnabled(Spass.DEVICE_FINGERPRINT_CUSTOMIZED_DIALOG) to return true for activation.

If the parameter is true, then

the UI is dismissed and you can receive
STATUS_USER_CANCELLED_BY_TOUCH_OUTSIDE as the event status in [Link]()
when touching background elements. If the parameter is false, the UI stays on screen regardless of
interactions with background elements.

setCanceledOnTouchOutside(boolean cancel);

if([Link](Spass.DEVICE_FINGERPRINT_CUSTOMIZED_DIALOG)){
[Link](true);
}
[Link]([Link],listener, true);

private [Link] listener =

new [Link]() {
...

5.13. Broadcast actions when registered fingerprint is

changed.
Samsung devices send broadcasts to apps when the registered fingerprint is changed. If a new fingerprint
is added, the app can get ACTION_FINGERPRINT_ADDED, while if a registered fingerprint is removed, the app
can get ACTION_FINGERPRINT_REMOVED. In these two cases, you can get the fingerprint index of the
fingerprint that is added or removed through the extra value of the intent. If all registered fingerprints are
removed, the app can get ACTION_FINGERPRINT_RESET.

ACTION_FINGERPRINT_RESET = "[Link].FINGERPRINT_RESET";
ACTION_FINGERPRINT_REMOVED = "[Link].FINGERPRINT_REMOVED";
ACTION_FINGERPRINT_ADDED = "[Link].FINGERPRINT_ADDED";

BroadcastReceiver mPassReceiver = new BroadcastReceiver() {

@Override
public void onReceive(Context context, Intent intent) {
final String action = [Link]();
if (SpassFingerprint.ACTION_FINGERPRINT_RESET.equals(action)) {
// when all fingerprint are removed

Copyright © Samsung Electronics Co., Ltd. All rights reserved. Page 18

 } else if (SpassFingerprint.ACTION_FINGERPRINT_REMOVED.equals(action)) {
int fingerIndex = [Link]("fingerIndex", 0);
// when specific fingerprint is removed
} else if (SpassFingerprint.ACTION_FINGERPRINT_ADDED.equals(action)) {
int fingerIndex = [Link]("fingerIndex", 0);
// when new fingerprint is added
}
}
};

5.14. Getting the guide when fingerprint recognition is

failed due to the poor quality.
When fingerprint recognition is failed due to the poor quality, you can get the string of guide for the reason.
This API must be called inside [Link]() with STATUS_QUALITY_FAILED in order for it to
return the string of guide. Otherwise, it returns null to indicate an invalid value.

[Link]();

private [Link] listener =

new [Link]() {
@Override
public void onFinished(int eventStatus) {
String FingerprintGuide = null;
if(eventStatus == SpassFingerprint.STATUS_QUALITY_FAILED){
FingerprintGuide = [Link]();
}
// It is called when fingerprint identification is finished.
}

5.15. Adding a button to the UI

This feature allows you to add the customized button on the UI before requesting fingerprint recognition.

If isFeatureEnabled(Spass. DEVICE_FINGERPRINT_AVAILABLE_PASSWORD) returns false, then this

function can be activated.

Calling the setDialogButton () method from the SpassFingerprint class allows you to set a button as a
own customized button. If the string is null, then the button would not be displayed in the UI.

If the customized button is set, then the UI is dismissed and you can receive STATUS_BUTTON_PRESSED as
the event status in [Link]() and connect your own menu for alternative.

mSpassFingerprint. setDialogButton (String buttonText);

Copyright © Samsung Electronics Co., Ltd. All rights reserved. Page 19

if(){
mSpassFingerprint. setDialogButton ("OWN BUTTON”);
}
[Link]([Link],listener, true);

private [Link] listener =

new [Link]() {
...

5.16. Changing a standby string to the UI

This feature allows you to change the standby string on the UI before requesting fingerprint recognition.

If isFeatureEnabled(Spass. DEVICE_FINGERPRINT_AVAILABLE_PASSWORD) returns false, then this

function can be activated.

Calling the changeStandbyString() method from the SpassFingerprint class allows you to change a
standby string as a own customized string. If the string is null, then the standby string would be displayed as
default in the UI.

mSpassFingerprint. changeStandbyString(String standbyText);

if(){
mSpassFingerprint. changeStandbyString ("Touch your fingerprint or press the button
for launching own menu”);
}
[Link]([Link],listener, true);

private [Link] listener =

new [Link]() {
...

Copyright © Samsung Electronics Co., Ltd. All rights reserved. Page 20

Copyright © Samsung Electronics Co., Ltd. All rights reserved. Page 21
Copyright

Copyright © 2014 Samsung Electronics Co. Ltd. All Rights Reserved.

Though every care has been taken to ensure the accuracy of this document, Samsung Electronics Co., Ltd.
cannot accept responsibility for any errors or omissions or for any loss occurred to any person, whether
legal or natural, from acting, or refraining from action, as a result of the information contained herein.
Information in this document is subject to change at any time without obligation to notify any person of
such changes.

Samsung Electronics Co. Ltd. may have patents or patent pending applications, trademarks copyrights or
other intellectual property rights covering subject matter in this document. The furnishing of this document
does not give the recipient or reader any license to these patents, trademarks copyrights or other
intellectual property rights.

No part of this document may be communicated, distributed, reproduced or transmitted in any form or by
any means, electronic or mechanical or otherwise, for any purpose, without the prior written permission of
Samsung Electronics Co. Ltd.

The document is subject to revision without further notice.

All brand names and product names mentioned in this document are trademarks or registered trademarks
of their respective owners.

For more information, please visit [Link]

Copyright © Samsung Electronics Co., Ltd. All rights reserved. Page 22