CardReader

Enterprise Browser 1.5

Overview

The Card Reader module decodes the card data when read through a card reader attachment. Currently this is available only on Symbol Technologies devices.Only the foreground application is given access to the card reader hardware, when an application is sent to the background its state will be saved and it will automatically relinquish control of the card reader. When brought back to the foreground, an application previously using the card reader will have its previous configuration (eg. pinTimeout) reapplied to the card reader automatically.

Enabling the API

There are two methods of enabling the CardReader API:

  • Include all ebapi modules
  • Include only the required API modules

For either of these methods, you'll need to include files from the /Enterprise Browser/JavaScript Files/Enterprise Browser directory on the computer that you installed the Enterprise Browser.

Include all JS API modules

To include all JS APIs, copy the ebapi-modules.js file to a location accessible by the app's files and include a reference to the JavaScript file in the app's HTML. For instance, to include the modules file in the app's index.html, copy the file to the same directory as that index.html and add the following line to the HTML's HEAD section:


<script type="text/javascript" charset="utf-8" src="ebapi-modules.js"></script>

Note: that the pathing for this file is relative to the current page.

This will define the EB class within the page. Any page you need to use the modules will need to have the .js file included in this fashion.

Include only the required modules

To include single APIs, you must first include the ebapi.js in your HTML as well as the API file you want to use. For instance, to use the CardReader API, I would add the following code to my HTML file(s), assuming the API files have been copied to the same directory as the HTML.


<script type="text/javascript" charset="utf-8" src="ebapi.js"></script>
<script type="text/javascript" charset="utf-8" src="eb.cardreader.js"></script>

The ebapi.js file is necessary for all single API inclusions.

Methods

close()

Closes the card reader.

Parameters

  • callback : CallBackHandler

Returns

Synchronous Return:

  • Void

Platforms

  • Android
  • Windows Mobile
  • Windows CE
  • Zebra Devices Only

Method Access:

  • Instance Method: This method can be accessed via an instance object of this class:
    • myObject.close()
  • Default Instance: This method can be accessed via the default instance object of this class.
    • EB.CardReader.close()

enumerate()

Enumerates all the available card readers.

Parameters

  • callback : CallBackHandler

Callback

Async Callback Returning Parameters: ARRAY

    • cardreaderArray : SELF_INSTANCE: EB.CardReader

Returns

Synchronous Return:

  • ARRAY : Array of Card reader objects.
    • cardreaderArray : SELF_INSTANCE: EB.CardReader

Platforms

  • Android
  • Windows Mobile

Method Access:

  • Class Method: This method can only be accessed via the API class object.
    • EB.CardReader.enumerate()

getAllProperties()

This method will return all of object/value pairs for the propertyNames of the API class.

Parameters

  • callback : CallBackHandler

Callback

Async Callback Returning Parameters: HASH

    • : STRING

Returns

Synchronous Return:

  • HASH : Map of all available properties
    • : STRING

Platforms

  • Android
  • Windows Mobile
  • Windows CE

Method Access:

  • Instance Method: This method can be accessed via an instance object of this class:
    • myObject.getAllProperties()
  • Default Instance: This method can be accessed via the default instance object of this class.
    • EB.CardReader.getAllProperties()

getDefault()

This method will return an object that represents the default instance of the API Class. For example Camera.getDefault will return a Camera object that represents the default camera.

Parameters

  • callback : CallBackHandler

Callback

Async Callback Returning Parameters: SELF_INSTANCE

    Returns

    Synchronous Return:

    • SELF_INSTANCE : Default object of Module.

    Platforms

    • Android
    • Windows Mobile
    • Windows CE

    Method Access:

    • Class Method: This method can only be accessed via the API class object.
      • EB.CardReader.getDefault()

    getProperties(ARRAY arrayofNames)

    This method will return a set of object/value pairs for the list of the propertyName that is passed in. The propertyNames must be a valid property of the API class.

    Parameters

    • arrayofNames : ARRAY

      List of properties I want to know about

      • Object : STRING

    • callback : CallBackHandler

    Callback

    Async Callback Returning Parameters: HASH

      • : STRING

    Returns

    Synchronous Return:

    • HASH : Map of properties I want to know about
      • : STRING

    Platforms

    • Android
    • Windows Mobile
    • Windows CE

    Method Access:

    • Instance Method: This method can be accessed via an instance object of this class:
      • myObject.getProperties(ARRAY arrayofNames)
    • Default Instance: This method can be accessed via the default instance object of this class.
      • EB.CardReader.getProperties(ARRAY arrayofNames)

    getProperty(STRING propertyName)

    This method will return the value of the propertyName that is passed in. The propertyName must be a valid property of the API class.

    Parameters

    • propertyName : STRING

      The property to return info about.

    • callback : CallBackHandler

    Callback

    Async Callback Returning Parameters: STRING

      Returns

      Synchronous Return:

      • STRING : The property to return info about.

      Platforms

      • Android
      • Windows Mobile
      • Windows CE

      Method Access:

      • Instance Method: This method can be accessed via an instance object of this class:
        • myObject.getProperty(STRING propertyName)
      • Default Instance: This method can be accessed via the default instance object of this class.
        • EB.CardReader.getProperty(STRING propertyName)

      open()

      Opens the card reader.

      Parameters

      • callback : CallBackHandler

      Callback

      Async Callback Returning Parameters: HASH

        • data : STRING

          Data read by the card reader. This may be card data, the PAN data extracted from the card data, encrypted PIN block data, or a message. In case of an ISO/ABA card [eg: a financial card], data is encrypted. For other cards, data is in the clear.

        • mode : STRING

          Describes the data. This will be either: 'CR','ENCDATA','PAN', or 'MESSAGE'. This equates to card data, encrypted PIN block data, PAN data, or a message, respectively.

        • encryption : BOOLEAN

          This provides the information regarding the card reader head configuration. Available only on Android.

        • rawData : STRING

          This is the raw data read by the card reader from all the tracks. Available only on Android and the value is in HEX format.

        • track1 : STRING

          The track1 clear/masked data read by the card reader. Available only on Android and the value is in HEX format. This value should be used only when the track1Status value returned is true.

        • track2 : STRING

          The track2 clear/masked data read by the card reader. Available only on Android and the value is in HEX format. This value should be used only when the track2Status value returned is true.

        • track3 : STRING

          The track3 clear/masked data read by the card reader. Available only on Android and the value is in HEX format. This value should be used only when the track3Status value returned is true.

        • track1Status : BOOLEAN

          The status of the track1 clear/masked data read by the card reader. Available only on Android.

        • track2Status : BOOLEAN

          The status of the track2 clear/masked data read by the card reader. Available only on Android.

        • track3Status : BOOLEAN

          The status of the track3 clear/masked data read by the card reader. Available only on Android.

        • track1Encrypted : STRING

          The track1 encrypted data read by the card reader. Available only on Android and the value is in HEX format. This value should be used only when the track1EncryptedStatus value returned is true.

        • track2Encrypted : STRING

          The track2 encrypted data read by the card reader. Available only on Android and the value is in HEX format. This value should be used only when the track2EncryptedStatus value returned is true.

        • track3Encrypted : STRING

          The track3 encrypted data read by the card reader. Available only on Android and the value is in HEX format. This value should be used only when the track3EncryptedStatus value returned is true.

        • track1EncryptedStatus : BOOLEAN

          The status of the track1 encrypted data read by the card reader. Available only on Android.

        • track2EncryptedStatus : BOOLEAN

          The status of the track2 encrypted data read by the card reader. Available only on Android.

        • track3EncryptedStatus : BOOLEAN

          The status of the track3 encrypted data read by the card reader. Available only on Android.

        • ksn : STRING

          The encrypted KSN serial number read by the card reader. Available only on Android. The value is in HEX format.

      Returns

      Synchronous Return:

      • Void

      Platforms

      • Android
      • Windows Mobile
      • Windows CE
      • Zebra Devices Only

      Method Access:

      • Instance Method: This method can be accessed via an instance object of this class:
        • myObject.open()
      • Default Instance: This method can be accessed via the default instance object of this class.
        • EB.CardReader.open()

      setDefault(SELF_INSTANCE: EB.CardReader defaultInstance)

      This method allows you to set the attributes of the default object instance by passing in an object of the same class.

      Parameters

      • defaultInstance : SELF_INSTANCE: EB.CardReader

        An instance object that is of the same class.

      • callback : CallBackHandler

      Returns

      Synchronous Return:

      • Void

      Platforms

      • Android
      • Windows Mobile
      • Windows CE

      Method Access:

      • Class Method: This method can only be accessed via the API class object.
        • EB.CardReader.setDefault(SELF_INSTANCE: EB.CardReader defaultInstance)

      setProperties(HASH propertyMap)

      This method will set the values of a list of properties for the API class. The propertyName must be a valid property for the class and must also not be read only.

      Parameters

      • propertyMap : HASH

        Map of properties I want to set

        • Object : STRING

      • callback : CallBackHandler

      Returns

      Synchronous Return:

      • Void

      Platforms

      • Android
      • Windows Mobile
      • Windows CE

      Method Access:

      • Instance Method: This method can be accessed via an instance object of this class:
        • myObject.setProperties(HASH propertyMap)
      • Default Instance: This method can be accessed via the default instance object of this class.
        • EB.CardReader.setProperties(HASH propertyMap)

      setProperty(STRING propertyName, STRING propertyValue)

      This method will set the value of a property for the API class. The propertyName must be a valid property for the class and must also not be read only.

      Parameters

      • propertyName : STRING

        The one property name that I want to set

      • propertyValue : STRING

        The one property value that I want to set

      • callback : CallBackHandler

      Returns

      Synchronous Return:

      • Void

      Platforms

      • Android
      • Windows Mobile
      • Windows CE

      Method Access:

      • Instance Method: This method can be accessed via an instance object of this class:
        • myObject.setProperty(STRING propertyName, STRING propertyValue)
      • Default Instance: This method can be accessed via the default instance object of this class.
        • EB.CardReader.setProperty(STRING propertyName, STRING propertyValue)

      Properties

      autoEnter

      Type

      BOOLEAN

      Description

      When enabled, appends a carriage return to any data returned as keystrokes by the cardreader. This is useful for auto submitting returned data without extra interaction necessary.

      Params

      Default: false

      Access

      • Instance: This property can be accessed via an instance object of this class: myObject.autoEnter
      • Default Instance: This property can be accessed via the default instance object of this class.
        • EB.CardReader.autoEnter

      Platforms

      • Android
      • Windows Mobile
      • Windows CE
      • Zebra Devices Only

      autoTab

      Type

      BOOLEAN

      Description

      When enabled, appends a tab to any data returned as keystrokes by the cardreader. This is useful when filling out a form so that you can move to the next field without extra interaction necessary.

      Params

      Default: false

      Access

      • Instance: This property can be accessed via an instance object of this class: myObject.autoTab
      • Default Instance: This property can be accessed via the default instance object of this class.
        • EB.CardReader.autoTab

      Platforms

      • Android
      • Windows Mobile
      • Windows CE
      • Zebra Devices Only

      moduleName

      Type

      STRING

      Description

      Deprecated This method is present to provide backwards compatibility with PocketBrowser code, devices supported by the Enterprise Browser will have a single card reader driver installed as part of the platform. If the device has multiple card reader drivers installed this parameter is used to select which driver to use. The drivers present are output in the log file when the card reader is initialized. This parameter is also used to distinguish between an MSR and a DCR, e.g. if you attach a DCR7000 to your device you can specify that only the MSR functionality is used by specifying this parameter as 'MSR7000'.

      Values

      Possible Values (STRING):

      • Constant: EB.CardReader.MSR9000 - String: msr9000 MSR9000 drivers. Return value while getting the property of moduleName will be its associated DLL name i.e. MSR3000.DLL.
      • Constant: EB.CardReader.MSR9001 - String: msr9001 MSR9001 drivers. Return value while getting the property of moduleName will be its associated DLL name i.e. MSR3000.DLL.
      • Constant: EB.CardReader.MSR9500 - String: msr9500 MSR9500 drivers. Return value while getting the property of moduleName will be its associated DLL name i.e. MSRMC50.DLL.
      • Constant: EB.CardReader.MSRCAMEO - String: msrcameo MSRCAMEO drivers. Return value while getting the property of moduleName will be its associated DLL name i.e. MSRCAMEO.DLL.
      • Constant: EB.CardReader.MSR7000 - String: msr7000 MSR7000 drivers. Return value while getting the property of moduleName will be its associated DLL name i.e. MSRMC50.DLL.
      • Constant: EB.CardReader.DCR7000 - String: dcr7000 DCR7000 drivers. Return value while getting the property of moduleName will be its associated DLL name i.e. MSRMC50.DLL.
      • Constant: EB.CardReader.MSR55 - String: msr55 MSR55 drivers. Return value while getting the property of moduleName will be its associated DLL name i.e. MSRMC55.DLL.
      • Constant: EB.CardReader.MSR3000 - String: msr3000 MSR3000 drivers. Return value while getting the property of moduleName will be its associated DLL name i.e. MSR3000.DLL.

      Access

      • Instance: This property can be accessed via an instance object of this class: myObject.moduleName
      • Default Instance: This property can be accessed via the default instance object of this class.
        • EB.CardReader.moduleName

      Platforms

      • Windows Mobile
      • Zebra Devices Only

      panData

      Type

      STRING

      Description

      Sets the card data without the need of a swipe. This accepts any 16 digit number as the string value. Ensure that pinEntry is true before getting the property of panData.

      Access

      • Instance: This property can be accessed via an instance object of this class: myObject.panData
      • Default Instance: This property can be accessed via the default instance object of this class.
        • EB.CardReader.panData

      Platforms

      • Windows Mobile
      • Zebra Devices Only(Only compatible with DCR7000-x00)

      pinEntry

      Type

      BOOLEAN

      Description

      Turns the PIN entry on or off.

      Access

      • Instance: This property can be accessed via an instance object of this class: myObject.pinEntry
      • Default Instance: This property can be accessed via the default instance object of this class.
        • EB.CardReader.pinEntry

      Platforms

      • Windows Mobile
      • Zebra Devices Only(Only compatible with DCR7000-x00)

      pinTimeout

      Type

      INTEGER

      Description

      PIN entry timeout in milliseconds. A value of 65535 sets the timeout to infinite. Accepts values between 0 and 65535.

      Params

      Default: 30000

      Access

      • Instance: This property can be accessed via an instance object of this class: myObject.pinTimeout
      • Default Instance: This property can be accessed via the default instance object of this class.
        • EB.CardReader.pinTimeout

      Platforms

      • Windows Mobile
      • Zebra Devices Only(Only compatible with DCR7000-x00)

      Remarks

      General

      If the CardReader open method is not specified with a callback, the cardreader data will be returned as keystrokes. If both the autotab and autoenter parameters are set to "enabled", autoenter will take precedence. An opened card reader must be closed before the attached card reader device and associated modulename parameter are changed. Any attempt to set a parameter to an invalid value, will result in no effect on the parameter's current value. There should be made a delay around 2 secs or more between API calls which interact with hardware.

      Operational Modes (Backwards compatibility with PocketBrowser)

      For the DCR7000 the ModuleName parameter must be set at least once before the readevent parameter is set. If the card reader is an MSR, when a card is swiped it returns the data read from the card. Setting ModuleName to a DCR will cause the card data to be returned followed by the PAN Data before waiting for a PIN to be entered on the keypad. Once entered the PIN will be encrypted and returned by a third ReadEvent. The card must be a validly formatted IATA or ABA card.

      Closing the reader while PIN entry pending

      There is no way to abort a pending PIN entry (other than the customer pressing the Cancel button), for security reasons. Therefore if the reader is closed or the Enterprise Browser is quit during that time it will become unresponsive until a PIN is entered or the PIN timeout occurs.

      Blank card data

      In certain circumstances it is possible that the card reader may return empty card data. The JavaScript event function should be able to handle this correctly.

      Detaching / Reattaching the Card Reader

      Applications running in the Enterprise Browser should be resilient against the card reader being detached and subsequently reattached. Card data parsing code should be robust against unexpected characters in the first read after reattachment.

      Encrypted Card data

      The encrypted data is supported only on the card readers that are configured for encryption. Since the encrypted data might contain unreadable characters sometimes it is recommended to use only JSON object method rather than JavaScript '%s' notation.

      Examples

      Accepting Card Swipes

      This example shows how to enable the card reader and accept a card swipe. It then, displays the data in a human readable way. This example assumes that the ebapi-modules.js file is in the same directory as the html file invoking it.

      
      
      <head>
          <script type="text/javascript" charset="utf-8" src="ebapi-modules.js"></script>
      
          <title>CardReader API Example</title>
      
          <script>
              var firstName  = '';
              var middleInit = '';
              var lastName   = '';
              var cardNumber = '';
      
              function openCardReader(){
                  EB.CardReader.open(cardReaderCallback);
              }
      
              function cardReaderCallback(params){
                  var scannedData = params['data'].split("^");
      
                  // The card number is preceded by a two characters: "%B" that need to be removed to display the number properly.
                  cardNumber = scannedData[0].substr(2);
      
                  var name  = scannedData[1];
                  lastName  = name.split("/")[0];
                  firstName = name.split("/")[1];
                  // Check for middle initial
                  if(firstName.split(" ")[1]){
                      middleInit = firstName.split(" ")[1];
                  }
      
                  cardData.innerHTML = 'Card Data: <br/>' + 
                                       'Name on Card: ' + firstName + ' ' + lastName + '<br/>' +
                                       'Card Number:  ' + cardNumber;
              }
          </script>
      </head>
      <body>
          <h1>CardReader API</h1>
          <br/>
          <br/>
          <div id='cardData'>Card Data: </div>
          <br/>
          <br/>
          <button onClick='openCardReader()'>Activate Card Reader</button>
      </body>