CardReader Module

The CardReader Module is used to either navigate to a URL or call a JavaScript function when an attached card reader decodes data.

• Syntax
• Methods
• Parameters
• Events
• Multi Instance
• Remarks
• Requirements
• HTML/JavaScript Examples

Syntax

Methods

Items listed in this section indicate methods or, in some cases, indicate parameters which will be retrieved.

Parameters

Items listed in this section indicate parameters, or attributes which can be set.

Events

Values are returned to the caller in RhoElements via Events. Most modules contain events and those returned from this module are given below along with the event parameters. Events can cause a navigation to a new URL or a JavaScript function on the page to be invoked. Each event will in most cases have a number of parameters associated with it which will either be strings or JavaScript arrays. Event parameters can be accessed either directly or via JSON objects.

readEvent

readEvent:URL(‘URI’) URI is either a URL or a JavaScript function. If a URL, the browser navigates to the URL when the attached card reader decodes some data. If a JavaScript function, the function is treated as a callback which is invoked when the card reader decodes data. Issuing this tag, automatically opens the card reader, if it has not been opened already.

Multi Instance

When multiple RhoElememts applications are running the following considerations should be made: Only the foreground RhoElements 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.

Remarks

General

If the CardReader return URI is “”, the cardreader data will be returned as keystrokes. The readevent parameter must be set at least once before the pandata parameter is set. 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.

AutoEnter and AccelerateKey

The AccelerateKey Meta tag controls the behaviour of Accelerate keys on Windows CE, if the Enter key is configured to be non functional then AutoEnter will also appear to not function either

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.

Event URI and Parameter Persistence

The ReadEvent URI, the PINTimeout, PINEntry, AutoEnter / AutoTab parameters are page-specific values. When RhoElements performs a page navigate (not a JavaScript callback), the URI is invalidated, the parameters set to their default values and the cardreader is closed. While the cardreader is open, the URI value may be changed via passing a new readevent parameter/value pair. In the case that the CardReader is already open, the readevent parameter will simply update the URI and do nothing to the state of the port.

Invalid parameter values

Any attempt to set a parameter to an invalid value, will result in no effect on the parameter’s current value.

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 RhoElements 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 RhoElements 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 readres 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.

Navigation to URL on ReadEvent

Because encrypted card data can contain characters not accepted in a URL the ReadEvent should be handled entirely in either JavaScript or Ruby.

Requirements

HTML/JavaScript Examples

The following example sets up the card reader to submit the scanned data to an asp page upon successful decoding

<META HTTP-Equiv="cardreader" Content="readevent:url('http://mypage.asp?Data=%s;Mode=%s')">

The following example sets up the card reader to call a JavaScript function upon successful decoding. The JavaScript function will be called 3 times, once with the raw card data, once with just the pan data extracted from the raw card data, and once with the encrypted pan data if the pin has been supplied by the user within 10s.:

<html>
    <head>
        <title>RhoElements CardReader Test</title>
        <meta http-equiv="content-type" content="text/html; charset=UTF-8">
        <meta HTTP-Equiv="CardReader" Content="PINEntry:ON">
        <meta HTTP-Equiv="CardReader" Content="PINTimeout:0x2710">
        <meta HTTP-Equiv="CardReader" Content="ReadEvent:url('javascript:doTransaction('%s', '%s');')">

        <script language="javascript" type="text/javascript">
            function doTransaction(data, mode){
                switch(mode) {
                    case 'CR':
                        alert('Card: '+data);
                        break;
                    case 'ENCDATA':
                        alert('Encoded data: '+data);
                        break;
                    case 'MESSAGE':
                        alert('Error: '+data);
                        break;
                    case 'PAN':
                        alert('PAN data: '+data);
                        alert('Please turn the unit over and enter the PIN');
                        break;
                }
            }
        </script>
    </head>
    <body>
    </body>
</html>

The following example closes the card reader

<META HTTP-Equiv="CardReader" Content="Close">

The following example reads the encrypted data from the card reader

<html>
    <head>
        <meta http-equiv="content-type" content="text/html; charset=UTF-8">
        <title>RhoElements CardReader data Test</title>
        <META HTTP-Equiv="CardReader" Content="ReadEvent:url('javascript:doTransaction(%json);')">
        <script language="javascript" type="text/javascript">
            function doTransaction(j){
                switch(j.mode) {
                    case 'CR':
                        htmlData.innerHTML = "Encryption = " + j.encryption + "<br>" 
                            + "Total data = " + j.data + "<br>"
                            + "Raw data = " + j.rawData + "<br>"
                            + "Unencrypted track1 data = " + j.track1 + "<br>"
                            + "Unencrypted track2 data = " + j.track2 + "<br>"
                            + "Unencrypted track3 data = " + j.track3 + "<br>"
                            + "Unencrypted track1 Status = " + j.track1Status + "<br>"
                            + "Unencrypted track2 Status = " + j.track2Status + "<br>"
                            + "Unencrypted track3 Status = " + j.track3Status + "<br>"
                            + "Encrypted track1 data = " + j.track1Encrypted + "<br>"
                            + "Encrypted track2 data = " + j.track2Encrypted + "<br>"
                            + "Encrypted track3 data = " + j.track3Encrypted + "<br>"
                            + "Encrypted track1 Status = " + j.track1EncryptedStatus + "<br>"
                            + "Encrypted track2 Status = " + j.track2EncryptedStatus + "<br>"
                            + "Encrypted track3 Status = " + j.track3EncryptedStatus + "<br>"
                            + "KSN number = " + j.ksn;
                            break;
                }
            }
        </script>
    </head>
    <body>
        <br><br><br><br><br>
        <DIV id="htmlData">The card data will appear here</div>
    </body>
</html>