Anleitung zur WebScan-JavaScript-API in iCody

WebScan enthält eine JavaScript-API, die von Ihren Websites verwendet werden kann, um gescannte Barcodes individuell zu verarbeiten (einschließlich AJAX usw.). Dabei gibt es zwei Wege, von Ihrer Website/WebApp mit iCody zu interagieren:

  • Die Javascript-Methodenaufrufe und
  • der Javacscript-Backchannel.

Die Javascript-Methodenaufrufe werden von iCody unmittelbar nach erfolgreichem Scan in WebScan durchgeführt, sofern dieses Feature aktiviert ist. Sie müssen dazu eine der folgenden Javascript-Funktionen in Ihrer WebApp implementiert haben:

icodyDidScanBarcode( value, typeID, typeValue, date );
oder
icodyDidScanBarcodeWithCoordinates( value, typeID, typeValue, date, latitude, longitude );
oder
icodyDidScanBarcodeWithCoordinatesAndUDID( value, typeID, typeValue, date, latitude, longitude, udid );
oder
icodyDidReadMagneticStripe(track1, track2, track3, typeID, type, date, latitude, longitude);

Neu in iCody 3.0:

icodyJSON(JSONString);

Bitte verwenden Sie am Besten nur noch diese Funktion, denn durch die Übergabe eines JSON-Strings erhalten Sie nur mit dieser Funktion auch alle Workflow-Komponenten.

Der Javascript-Backchannel erlaubt Ihnen, Kommandos an iCody zu senden – unabhängig vom Scanvorgang. Sie erlauben die Interaktion mit dem User und unterscheiden sich nach dem synchronen Verfahren und dem asynchronen Verfahren:  Der synchrone Backchannel erlaubt Ihnen die Rückgabe von Kommandos als Ergebnis der o.g. Methoden, die iCody aufgerufen hat. Der asynchrone Backchannel funktioniert losgelöst vom JS-Methodenaufruf und erlaubt Ihnen, die Kommandos an iCody zu “pushen”. Dabei kommt eine Javascript window.location Aufruf mit einem besonderen URL-Schema zum Einsatz.

JSAPI-de

Um in Ihrer WebApp Javascript-Funktionsaufrufe von iCody zu erhalten, müssen zwei Voraussetzungen erfüllt sein:

1. Aktivieren Sie “JavaScript-Funktionen Aufrufen” in den iCody-Einstellungen. Es ist empfehlenswert, die Funktion “In das aktive Feld schreiben” zu deaktivieren.

2. Implementieren Sie (eine der) folgende(n) JavaScript-Funktionen in Ihrer Website (beide werden aufgerufen, aber es empfiehlt sich, nur eine der beiden zu verwenden):

function icodyDidScanBarcode( value, typeID, typeValue, date ) {
		// Ihr Code hier
	return <cmdlist>;
}
function icodyDidScanBarcodeWithCoordinates( value, typeID, typeValue, date, latitude, longitude ) {
		// Ihr Code hier
	return <cmdlist>;
}

Beide Funktionen können als Ergebnis eine Kommando-Liste zurück geben, die in iCody verarbeitet wird. Dies ist der synchrone Backchannel. Sie müssen diesen Rückgabewert aber nicht implementieren, die Funktionen können auch “nichts” als Rückgabewert liefern.

Der asynchrone Backchannel wird unabhängig von den Javascript-Funktionsaufrufen ausgelöst, indem in Ihrer Javascript-Implementierung innerhalb des WebScan-Fensters ein window.location-Aufruf mit dem iCody-URL-Schema (icody://) ausgeführt wird:

window.location = “icody://<cmd>?<parameters>”;

Bitte beachten Sie, dass alles nach dem icody:// URL-encodierd (Prozent-Encoding) sein muss.

Hier eine Aufstellung der zulässigen und unterstützen Kommandos und Parameter:

sound Einen Sound abspielen.
  name Typ-ID:playSuccessSound, playFailureSound
  repeat Anzahl von Wiederholungen (0 = keine)
vibrate Das Gerät vibrieren lassen (keine Parameter)
scan Scanvorgang starten (Keine Parameter). Das Ergebnis wird wie ein normales Scanergebnis behandelt.Hinweis: Dieser Funktionsaufruf funktioniert nur bedingt mit externen Scanner (Linea Pro usw.), da hier der Scanvorgang i.d.R. an den Scanbutton am Gerät gekoppelt ist.
showcontrols WebScan-Controls einblenden (nur im Kiosk-Mode, keine weiteren Parameter).
hidecontrols WebScan-Controls ausblenden (nur im Kiosk-Mode, keine weiteren Parameter).
setdefaulturl Speichert den Parameter-Wert als Default-URL und überschreibt etwaige Einstellungen in den iCody-Einstellungen.
  value die neue URL
alert Eine Alertbox anzeigen.
  title der Titel der Alertbox
  message die anzuzeigende Nachricht
  defaultbutton der Text des Default-Buttons (zumeist OK oder Abbruch)
  cancelbutton der Text eines Abbruch-Buttons (optional)
  location eine URL, die geöffnet wird, wenn der Nutzer den defaultButton gedrückt wird.
print Die übergebenen Druck-Kommandos verarbeiten(NICHT im synchronen Backchannel verfügbar)
  device derzeit nur Modus linea unterstütztHinweis: Drucken erfordert Linea Pro mit Bluetooth-Modul und einen verbundenen DPP-xxx-Drucker.
  commands die Druckkommandos (eine Dokumentation der HTTP-Post-Verbindungs-API)

Wichtige Hinweise: Obwohl der asynchrone Backchannel ebenfalls das icody://-URL-Schame verwendet ist er NICHT kompatibel zum Callback-Verfahren.

 

Beispiele:
Das folgende JavaScript-Snippet spielt im synchronen Verfahren zweimal einen Erfolg-Sound, lässt das Gerät vibrieren und zeigt eine Alertbox:

<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>

 

Das folgende JavaScript-Snippet präsentiert eine einfache Alertbox im asynchronen Verfahren und leitet zur Google-Suche weiter, sobald der Benutzer “OK” drückt:

<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>

 

Dieses Beispiel verdeutlicht, wie mit einem DPP-xxx oder PP-60 gedruckt werden kann. Zunächst sehen Sie das Druck-Kommando-Array, das das gespeicherte Logo und “Text” ausdruckt. Darunter finden Sie eine Umsetzung als Javascript-Snippet. Bitte beachten Sie, dass alles nach icody:// URL-encodiert ist – einschließlich des Kommando-Arrays:

<?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>