JavaScript API

TheFlex stellt für Webseiten/Fiori-Apps eine JavaScript API bereit, um native Gerätefunktionen nutzen zu können (z. B. Scanner, Intents, Tastatur, Logging, Device-Infos).

API-Übersicht (Module)

Die API ist in folgende Bereiche gegliedert:

flx.zebra – Zebra DataWedge / Scanning
flx.cipherlab – Cipherlab OCR Trigger
flx.deviceInfo – Geräte-/Terminaldaten
flx.log – Logging (fatal/error/warn/info/…)
flx.backhandscanner – Handrückenscanner (paired device)
flx.keyboard – Tastatur + Barcode-„Eingabe“
flx.intents – Android Intent Listener (generisch)
flx.copyAndPaste – Copy/Paste blockieren/erlauben

Die API steht nach deviceready zur Verfügung und wird über Cordova require geladen:

document.addEventListener("deviceready", function () {
  const flx = cordova.require("de.flexus.flxcoreplugin.flxmainplugin");

  // Beispiel: Tastatur ausblenden
  flx.keyboard.hide();

  // Beispiel: Log
  flx.log.info("TheFlex API ready");
});

Hinweis

Die darunterliegenden Plugins/Objekte (z. B. flxDatawedge, Keyboard, …) werden von TheFlex bereitgestellt. Sie müssen nicht separat geladen oder eingebunden werden.

Zebra DataWedge

DataWedge Intent-Konfiguration

Damit Scan-Daten per Intent an die Web-App geliefert werden können:

DataWedge App öffnen
Profil auswählen oder erstellen
Tastatur-Ausgabe deaktivieren
Intent-Ausgabe aktivieren
- Action: zebra.scan
- Intent-Übertragung: „Intent senden“

Zebra API (flx.zebra)

flx.zebra.createProfile(profileName, success, error)

Erstellt ein neues DataWedge-Profil.

flx.zebra.createProfile(
  "MY_PROFILE",
  () => console.log("Profile created"),
  (e) => console.error("Error", e),
);

flx.zebra.enableScanner(success, error)

Aktiviert den Scanner.

flx.zebra.enableScanner(
  () => console.log("Scanner enabled"),
  (e) => console.error(e),
);

flx.zebra.disableScanner(success, error)

Deaktiviert den Scanner.

flx.zebra.setActiveProfile(success, error)

Setzt ein Profil als aktiv.

Hinweis

In der aktuellen Wrapper-Signatur wird kein profileName übergeben. Falls ihr das Aktivieren per Name benötigt, passt den Wrapper an oder nutzt die darunterliegende Implementierung.

flx.zebra.enableDecoders(profileName, decoders, success, error)

Aktiviert bestimmte Decoder für ein Profil.

decoders: typischerweise eine Liste/Map je nach Implementierung.

flx.zebra.resetDecoders(profileName, success, error)

Setzt alle Decoder-Einstellungen eines Profils zurück.

Zebra Scan Listener

flx.zebra.startScanListener(success, error)

Startet einen Listener, um Scan-Ergebnisse im JavaScript zu verarbeiten.

Erwartetes Ergebnisobjekt (typisch):

result.data
result.decodeMode
result.barcodeType

Beispiel: Scan-Ergebnis anzeigen

document.addEventListener("deviceready", function () {
  const flx = cordova.require("de.flexus.flxcoreplugin.flxmainplugin");

  flx.zebra.startScanListener(
    function (result) {
      alert(result.decodeMode + " " + result.barcodeType + " " + result.data);
    },
    function (e) {
      alert("Error in scan listener: " + e);
    },
  );
});

Beispiel: Scan zuschneiden und in aktives Eingabefeld schreiben

document.addEventListener("deviceready", function () {
  const flx = cordova.require("de.flexus.flxcoreplugin.flxmainplugin");

  flx.zebra.startScanListener(
    function (result) {
      const scanData =
        typeof result === "object" && result.data ? result.data : "";
      if (!scanData) return;

      const cut =
        scanData.length > 6 ? scanData.substr(3, scanData.length - 6) : "";
      const active = document.activeElement;

      if (
        active &&
        (active.tagName === "INPUT" || active.tagName === "TEXTAREA")
      ) {
        active.value = cut;
        active.dispatchEvent(new Event("input"));
      } else {
        alert("No input field focused!");
      }
    },
    function (e) {
      alert("Error in scan listener: " + e);
    },
  );
});

flx.zebra.stopScanListener(success, error)

Stoppt den Listener und stellt das normale Scanverhalten wieder her.

Cipherlab (OCR)

Um das OCR-Plugin auf Ihrer Webseite zu verwenden, stellen Sie sicher, dass Sie die folgenden Punkte beachten:

Optionale Parameter:

Ab dem Parameter limit_area sind alle nachfolgenden Parameter optional. Wenn Sie keine Begrenzung der Erfassungsfläche benötigen, setzen Sie limit_area auf 0. Die folgenden Parameter sind dann optional und können ebenfalls auf 0 gesetzt oder weggelassen werden:

limit_area_width_for_portrait
limit_area_height_for_portrait
limit_area_width_for_landscape
limit_area_height_for_landscape
limit_area_width_for_real_time
limit_area_height_for_real_time
limit_area_width_for_reader_camera
limit_area_height_for_reader_camera
limit_area_width_for_reader_camera_real_time
limit_area_height_for_reader_camera_real_time

Zusätzlich können Sie text_rules anpassen oder entfernen, wenn keine benutzerdefinierten Texterkennungsvorschriften erforderlich sind.

Beispiel für die Verwendung:

Um das OCR-Plugin zu nutzen, können Sie den folgenden JavaScript-Code verwenden:

var config = {
  enable_settings: true,
  reader_camera_mode: 0,
  action_mode: 1,
  text_recognition_mode: 1,
  remove_blank_chars: 1,
  zoom_ratio: 1.5,
  save_picture: 0,
  limit_area: 1, // Setzen Sie auf 0, wenn keine Begrenzung benötigt wird
  limit_area_width_for_portrait: 0.8, // Optional
  limit_area_height_for_portrait: 0.1, // Optional
  limit_area_width_for_landscape: 0.6, // Optional
  limit_area_height_for_landscape: 0.3, // Optional
  limit_area_width_for_real_time: 0.8, // Optional
  limit_area_height_for_real_time: 0.1, // Optional
  limit_area_width_for_reader_camera: 0.8, // Optional
  limit_area_height_for_reader_camera: 0.1, // Optional
  limit_area_width_for_reader_camera_real_time: 0.8, // Optional
  limit_area_height_for_reader_camera_real_time: 0.1, // Optional
  text_rules: [
    // Optional
    "([0-9])([0-9])([0-9])([0-9])([-|/])([0-1])([0-9])([-|/])([0-3])([0-9])",
    "^[-+]{0,1}[0-9]*$",
  ],
};

flxOcrTrigger.triggerOCR(
  config,
  function (result) {
    console.log("OCR Result:", result);
  },
  function (error) {
    console.error("OCR Error:", error);
  },
);

Device Info

flx.deviceInfo.getDeviceData(success)

Liefert Geräteinformationen.

flx.deviceInfo.getDeviceData(function (data) {
  console.log("deviceData", data);
});

flx.deviceInfo.getTerminalData(success)

Liefert Terminal-/MDM-/TheFlex relevante Terminaldaten.

flx.deviceInfo.getTerminalData(function (data) {
  console.log("terminalData", data);
});

flx.deviceInfo.getWebviewVersion()

Gibt die WebView-Version zurück.

const version = flx.deviceInfo.getWebviewVersion();
console.log("webview", version);

Logging

flx.log.fatal(message)
flx.log.error(message)
flx.log.warn(message)
flx.log.info(message)
flx.log.log(message)
flx.log.debug(message)
flx.log.trace(message)

Beispiel

flx.log.info("User opened page X");
flx.log.warn("Slow response on endpoint Y");
flx.log.error("Login failed");

Handrückenscanner

Weitere Informationen wie man ein Handrückensscanner konfiguriert, findet man hier.

flx.backhandscanner.init()

Initialisiert die Scanner-Anbindung.

flx.backhandscanner.connect()

Verbindet den Scanner.

flx.backhandscanner.disconnect()

Trennt die Verbindung.

flx.backhandscanner.checkConnection(success, error)

Prüft Verbindungsstatus.

flx.backhandscanner.checkConnection(
  (status) => console.log("connected?", status),
  (e) => console.error(e),
);

flx.backhandscanner.typeBarcodeScan(data)

„Tippt“ (simuliert) Barcode-Daten in die aktuelle Eingabe.

flx.backhandscanner.setDisplayXML(xml)

Setzt Display-Inhalt via XML (geräteabhängig).

flx.backhandscanner.setDisplay(arg, success, error)

Setzt Display-Inhalt über Argument-Objekt (geräteabhängig).

Tastatur

flx.keyboard.show()

Zeigt die Tastatur an.

flx.keyboard.hide()

Blendet die Tastatur aus.

Hinweis

Intern wird dafür das Cordova Keyboard Plugin genutzt. Dieses muss in euren Webprojekten i. d. R. nicht separat eingebunden werden, da TheFlex es bereitstellt.

flx.keyboard.enterBarcodeData(value)

Schreibt Barcode-Daten programmatisch in den vorgesehenen Eingabekanal (TheFlex-intern).

flx.keyboard.enterBarcodeData("1234567890");

NFC

Weitere Informationen zur NFC Integration findet man hier.

TheFlex stellt (sofern das Gerät NFC unterstützt) die Cordova NFC API bereit. Du kannst damit NFC-Tags erkennen, NDEF-Daten lesen und NDEF-Daten schreiben.

Hinweis

NFC muss am Gerät aktiviert sein. Wenn window.nfc nicht existiert, wird NFC auf dem Gerät/Setup nicht unterstützt.

NFC verfügbar/aktiviert prüfen

document.addEventListener("deviceready", function () {
  if (!window.nfc) {
    console.log("NFC not available on this device.");
    return;
  }

  nfc.enabled(
    () => console.log("NFC enabled"),
    (err) => console.log("NFC not enabled: " + JSON.stringify(err)),
  );
});

NDEF lesen

document.addEventListener("deviceready", function () {
  if (!window.nfc) return;

  nfc.addNdefListener(
    function (nfcEvent) {
      const tag = nfcEvent.tag;
      const uid = nfc.bytesToHexString(tag.id);
      const msg = tag.ndefMessage || [];

      console.log("NFC UID:", uid);
      if (msg.length > 0) {
        const text = ndef.textHelper.decodePayload(msg[0].payload);
        console.log("NDEF text:", text);
      }
    },
    () => console.log("NDEF listener registered"),
    (e) => console.log("Failed to register listener: " + JSON.stringify(e)),
  );
});

NDEF schreiben (Textrecord)

function writeNfcText(text) {
  const message = [ndef.textRecord(text)];

  nfc.write(
    message,
    () => console.log("NFC tag written"),
    (e) => console.log("Write failed: " + JSON.stringify(e)),
  );
}

Intents

Für generische Intent-Verarbeitung (unabhängig von DataWedge-Wrappern).

flx.intents.startScanListener(success, error)

Startet einen Intent-basierten Scan-Listener (Plugin: flxIntentPlugin).

flx.intents.stopScanListener(success, error)

Stoppt den Listener.

flx.intents.addIntentListener(params, success, error)

Registriert einen Listener für bestimmte Intent-Parameter.

flx.intents.addIntentListener(
  { action: "zebra.scan" },
  (intent) => console.log("intent received", intent),
  (e) => console.error(e),
);

flx.intents.removeAllIntentReceivers()

Entfernt alle registrierten Intent-Receiver.

Copy & Paste blockieren

flx.copyAndPaste.enableBlock()

Blockiert Copy & Paste.

flx.copyAndPaste.disableBlock()

Erlaubt Copy & Paste wieder.

flx.copyAndPaste.isBlockEnabled(success, error)

Fragt ab, ob die Sperre aktiv ist.

flx.copyAndPaste.isBlockEnabled(
  (enabled) => console.log("blockEnabled", enabled),
  (e) => console.error(e),
);

(Deprecated) Launchpad-Daten

Beim Anlegen einer Startseite können Benutzername/Passwort für die Vorbelegung in Fiori-Apps hinterlegt werden.

Hinweis

Falls eure Implementierung weiterhin FlxMultiUrls.currentLaunchpadData nutzt, kann das unverändert bleiben. Die neue Strukturierung oben betrifft primär die nativen Plugin-Funktionen.

// Liefert alle Daten zum aktuellen Launchpad
FlxMultiUrls.currentLaunchpadData;

// Einzelne Felder
FlxMultiUrls.currentLaunchpadData.Name;
FlxMultiUrls.currentLaunchpadData.URL;
FlxMultiUrls.currentLaunchpadData.Username;
FlxMultiUrls.currentLaunchpadData.Password;

Achtung

Jede Webseite kann diese Daten auslesen. Benutzername/Passwort nur verwenden, wenn ausschließlich interne Webseiten/Apps geöffnet werden, über die ihr die volle Kontrolle habt.

Migrationshinweis (alt → neu)

Wenn ihr bisher direkt auf globale Objekte gegangen seid (z. B. flxDatawedge.startScanListener(...) oder Keyboard.hide()), nutzt künftig bevorzugt:

flxDatawedge.* → flx.zebra.*
Keyboard.hide()/show() → flx.keyboard.hide()/show()
flxlog.* → flx.log.*
flxPairedDevice.* → flx.backhandscanner.*
plugins.flxIntentPlugin.* → flx.intents.*
flxBlockCopyPaste.* → flx.copyAndPaste.*

Damit bleibt die Oberfläche sauber und die API ist konsistent nach Funktionsbereichen gegliedert.

API-Übersicht (Module)​

Zebra DataWedge​

DataWedge Intent-Konfiguration​

Zebra API (flx.zebra)​

Zebra Scan Listener​

Cipherlab (OCR)​

Device Info​

Logging​

Handrückenscanner​

Tastatur​

NFC​

Intents​

Copy & Paste blockieren​

(Deprecated) Launchpad-Daten

Migrationshinweis (alt → neu)​

API-Übersicht (Module)

Zebra DataWedge

DataWedge Intent-Konfiguration

Zebra API (flx.zebra)

Zebra Scan Listener

Cipherlab (OCR)

Device Info

Logging

Handrückenscanner

Tastatur

NFC

Intents

Copy & Paste blockieren

Migrationshinweis (alt → neu)