Guide to iCody’s WebScan JavaScript API

iCody’s WebScan Javascript API contains two parts:

  • The Javascript method calls and
  • the Javascript back channel.

The Javascript method calls are performed by iCody immediately after a succesful scan and when this feature is enabled and WebScan is active. Developers have to implement one of the following methods into their WebApp HTML code:

(Note: These method calls are deprecated, use icodyJSON() instead)

icodyDidScanBarcode( value, typeID, typeValue, date );

or

icodyDidScanBarcodeWithCoordinates( value, typeID, typeValue, date, latitude, longitude );

or

icodyDidScanBarcodeWithCoordinatesAndUDID( value, typeID, typeValue, date, latitude, longitude, udid );

or

icodyDidReadMagneticStripe(track1, track2, track3, typeID, type, date, latitude, longitude);

New in iCody 3.0:

icodyJSON(JSONString);

It is highly recommended to only use this method call, since only this call receives all workflow items when called.

The Javascript back channel allows you to send commands back to iCody. These commands will be processed by iCody and allow you to interact with iCody’s user. Basically there are two different ways to send data back: The synchronous and the asynchronous way: The synchronous back channel lets you return command information to iCody when the Javascript method call is processed. This is simply the return value of on of the Javascript API method calls. The asynchronous back channel gives you the possibility to “push” commands to iCody whenever you like by using a window.location call with a certain URL scheme.

JSAPI-de

To receive Javscript function calls, two prerequisites must be met:

  1. In the settings pane of iCody, enable “Call JavaScript functions” setting. It is also recommended to disable the “Write into active field” setting.
  2. On your website, implement (one of) the following Javascript functions (Both functions will get called but it is recommended to only implement on of them):function icodyDidScanBarcode( value, typeID, typeValue, date ) {
    // your implementation here
    return ;
    }
    function icodyDidScanBarcodeWithCoordinates( value, typeID, typeValue, date, latitude, longitude ) {
    // your implementation here
    return ;
    }

    function icodyDidScanBarcodeWithCoordinatesAndUDID( value, typeID, typeValue, date, latitude, longitude, udid ) {
    // your implementation here
    return ;
    }

Both functions may return a command list which causes iCody to react in certain ways on the result of your custom functions. You may use them but you do not have to.

The asynchronous back channel is initiated by a Javascript window.location call within the WebScan view using the icody:// URL scheme at any time:

window.location = "icody://?";

Please note that the entire subpart after icody:// has to be URL encoded (percent eoncoding).

These are the possible commands and their paramters:

sound

Play a sound

name Type ID:

playSuccessSound, playFailureSound

repeat # of repeats (0 = none)

vibrate

Let the device vibrate (no parameters)

scan

Start scanner (no parameters). The result will be processed like any other scan result.
Note: This might work with limitations only with external scanner accessories since these devices usually rely on their external scan button.

showcontrols

Show WebScan controls (no further parameters, only when Kiosk mode is disabled).

hidecontrols

Hide WebScan controls (no further parameters, only when Kiosk mode is disabled).

setdefaulturl

Stores the passed value as (new) default URL and overwrites the setting made on the device.

value the new URL

alert

Show an alert to the user

title the alert box’s title

message the message to show

defaultbutton the default button to show (OK)

cancelbutton the cancel button text to show (optional)

location an URL to jump in WebScan to in case the defaultbutton was pressed (optional)

print

Process the provided print command array
(NOT availble in synchronous back channel)

device currently only linea supported
Note: Printing to these devices needs either a Linea Pro with bluetooth module and a connected DPP-xxx printer or a PP-60 device.

commands printing commands
(Please refer to the HTTP Post connection type API description for more details)

Please note: Allthough the WebScan back channel uses the icody:// URL scheme as well, this mode is NOT compatible to the callback mechanism.

Examples:
The following JavScript-Snippet uses the synchronous back channel and plays two success sound, lets the device vibrate und shows an alert box:

<script type="text/javascript">
function icodyDidScanBarcode( value, typeID, typeValue, date ) {
/* ... Ihr Code ... */
var retval = new Array( "playSuccessSound:1", "vibrate", "showAlert:Message here:Title here:OK:Discard barcode" );
return retval.join(";");
}

</script>

The following JavaScript uses the asynchronous back channel and simply prompts an alert to the user and redirects him to the google search (query: “Test”) if one confirms (OK):

<script type="text/javascript">
window.location = "icody://alert?title=Error&message=message&defaultbutton=OK&cancelButton=Cancel&location=http%3A%2F%2Fwww.google.de%2Fsearch%3Fq%3DTest";
</script>

This example shows how to print to the connected DPP-xxx printer or PP-60. First you can see the print command array which prints the stored logo and the Text “Text”, and below, the necessary Javascript is shown. Please be aware that the whole subpart after icody:// is URL encoded – including the command plist (of course the whitespaces might be removed):

<?xml version="1.0" encoding="UTF-8"?>
<plist version="1.0">
<array>
<dict>
<key>cmd</key>
<string>PCLGO</string>
</dict>
<dict>
<key>cmd</key>
<string>PCPT</string>
<key>value</key>
<string>{==}{+B}Text\n</string>
</dict>
<dict>
<key>cmd</key>
<string>PCFLSH</string>
</dict>
</array>
</plist>

<script type="text/javascript">
window.location = "icody://print?device=linea&commands=%3C%3Fxml%20version%3D%221.0%22%20encoding%3D%22UTF-8%22%3F%3E%0A%3C!DOCTYPE%20plist%20PUBLIC%20%22-%2F%2FApple%2F%2FDTD%20PLIST%201.0%2F%2FEN%22%20%22http%3A%2F%2Fwww.apple.com%2FDTDs%2FPropertyList-1.0.dtd%22%3E%0A%3Cplist%20version%3D%221.0%22%3E%0A%09%09%3Carr..."
</script>