Modules.TouchId

Submodule of Modules.
Platform Since
iPhone 3.4.0
iPad 3.4.0

Description

Allows a Titanium application to use the iOS Touch ID authentication mechanism.

Touch ID is a security mechanism that uses a fingerprint to authenticate the user. The fingerprint sensor is located in the Home button of the device. Users can use their fingerprint instead of entering their passcode for authentication.

Requirements

The Touch ID module is available with the Titanium SDK starting with Release 3.4.0. This module only works with devices running iOS 8. You can only test the Touch ID module on a device.

The device must have a Touch ID sensor in the Home button and Touch ID must be setup in order to use the Touch ID authentication mechanism. You can set up Touch ID in iOS Setup Assistant or by tapping Touch ID & Passcode from Settings.

For information on setting up Touch ID, see iPhone 5s: Using Touch ID.

Getting Started

Add the module as a dependency to your application by adding a <module> item to the <modules> element of your tiapp.xml file:

<ti:app>
  ...
  <modules>
    <module platform="iphone">ti.touchid</module>
  </modules>
  ...
</ti:app>

Use require() to access the module from JavaScript:

var TouchId = require("ti.touchid");

The TouchId variable is a reference to the module. Make API calls using this reference:

TouchId.authenticate({
    reason: "Need to modify personal settings.",
    callback: authCB
});

Sample Application

The module contains a sample application in the <TITANIUM_SDK_HOME>/modules/iphone/ti.touchid/<VERSION>/example/ folder.

Properties

ERROR_AUTHENTICATION_FAILED : Number read-only

Constant indicating that the authentication was not successful.

ERROR_PASSCODE_NOT_SET : Number read-only

Constant indicating that the passcode is not set for the device.

ERROR_SYSTEM_CANCEL : Number read-only

Constant indicating that iOS cancelled authentication, for example, if another application enters the foreground.

ERROR_TOUCH_ID_NOT_AVAILABLE : Number read-only

Constant indicating that Touch ID is not available on the device.

ERROR_TOUCH_ID_NOT_ENROLLED : Number read-only

Constant indicating that Touch ID does not have any enrolled fingerprints.

ERROR_USER_CANCEL : Number read-only

Constant indicating that the user canceled authentication.

ERROR_USER_FALLBACK : Number read-only

Constant indicating that the user tapped the fallback button to enter their passcode.

apiName : String read-only

The name of the API that this proxy corresponds to.

Description

The value of this property is the fully qualified name of the API. For example, Button returns Ti.UI.Button.

bubbleParent : Boolean

Indicates if the proxy will bubble an event to its parent.

Description

Some proxies (most commonly views) have a relationship to other proxies, often established by the add() method. For example, for a button added to a window, a click event on the button would bubble up to the window. Other common parents are table sections to their rows, table views to their sections, and scrollable views to their views. Set this property to false to disable the bubbling to the proxy's parent.

Methods

addEventListener

Adds the specified callback as an event listener for the named event.

  • Parameters

    • name : String

      Name of the event.

    • callback : Callback<Object>

      Callback function to invoke when the event is fired.

  • Returns

    void

applyProperties

Applies the properties to the proxy.

Description

Properties are supplied as a dictionary. Each key-value pair in the object is applied to the proxy such that myproxy[key] = value.

  • Parameters

    • props : Dictionary

      A dictionary of properties to apply.

  • Returns

    void

authenticate

Initiates the Touch ID authentication process.

  • Parameters

    • params : Dictionary

      Dictionary containing two properties:

      • reason (String): Message displayed in the authentication dialog describing why the application is requesting authentication.
      • callback (Function): Callback function executed after the authentication completes. The callback function is passed a dictionary with three properties:

        • success (Boolean): Set to true if authentication succeeded.
        • error (String): System error message.
        • code (Number): Module ERROR_* constant indicating the reason for the failure.
  • Returns

    void

fireEvent

Fires a synthesized event to any registered listeners.

  • Parameters

    • name : String

      Name of the event.

    • event : Dictionary

      A dictionary of keys and values to add to the Titanium.Event object sent to the listeners.

  • Returns

    void

getApiName

Gets the value of the apiName property.

  • Returns

    String

getBubbleParent

Gets the value of the bubbleParent property.

  • Returns

    Boolean

removeEventListener

Removes the specified callback as an event listener for the named event.

Description

Multiple listeners can be registered for the same event, so the callback parameter is used to determine which listener to remove.

When adding a listener, you must save a reference to the callback function in order to remove the listener later:

var listener = function() { Ti.API.info("Event listener called."); }
window.addEventListener('click', listener);

To remove the listener, pass in a reference to the callback function:

window.removeEventListener('click', listener);
  • Parameters

    • name : String

      Name of the event.

    • callback : Callback<Object>

      Callback function to remove. Must be the same function passed to addEventListener.

  • Returns

    void

setBubbleParent

Sets the value of the bubbleParent property.

  • Parameters

    • bubbleParent : Boolean

      New value for the property.

  • Returns

    void

Events

This type has no events.