How to Integrate jZebra with Your POS System: Step-by-Step
Integrating jZebra (now known as QZ Tray in later forks) with your POS system lets you print receipts, labels, and tickets directly to local or networked printers from a browser or desktop application. This guide assumes a typical POS stack: a web-based frontend (HTML/JS), a backend server (Node.js/PHP/Java), and thermal/label printers that accept ESC/POS or ZPL commands. I’ll provide a clear, prescriptive integration path with code examples and troubleshooting tips.
Prerequisites
- A POS web frontend (HTML/JS) and a server you control.
- jZebra (or QZ Tray) installed on client machines that will print.
- Printer drivers installed on client machines, or network-accessible printers that accept raw commands.
- Basic familiarity with JavaScript and your backend language.
Overview (high level)
- Install jZebra/QZ Tray on client machines.
- Include the jZebra JavaScript client in your POS frontend.
- Establish a connection from the browser to jZebra.
- Send raw printer commands or formatted data from your POS to the printer via jZebra.
- Handle permissions, certificate signing (if using QZ Tray), and fallbacks.
Step 1 — Install jZebra / QZ Tray on client machines
- Download QZ Tray (recommended fork of jZebra) from its official site and install on each POS terminal.
- Ensure the jZebra/QZ Tray service is running and allowed through local firewalls.
- Configure printers in OS settings so they’re available to the service.
Step 2 — Add the jZebra JavaScript client to your frontend
Include the client script served by the local jZebra/QZ Tray service. Example for QZ Tray (adjust host/port if different):
html
<script src=“http://localhost:8181/qz-tray.js”></script>
For older jZebra builds, script names or ports may differ (commonly 4444 or 8080). Use the local service URL shown in the installed app.
Step 3 — Connect from browser to jZebra
Use the JS API to establish a connection. Example (QZ Tray):
js
// Connect qz.websocket.connect().then(() => { console.log(“Connected to QZ Tray”); }).catch(err => { console.error(“Connection failed:”, err); });
For older jZebra instances, APIs differ (e.g., jzebra.startPrinter()). Consult the specific library docs if you get errors.
Step 4 — Discover printers and select one
List available printers and select the desired one:
js
qz.printers.find().then(printers => { console.log(“Available printers:”, printers); // Choose a default (first) or match by name return printers.find(p => p.includes(“Your Printer Name”)) || printers[0]; }).then(printer => { console.log(“Using printer:”, printer); });
Step 5 — Prepare print data (raw commands or images)
Options:
- Send ESC/POS or ZPL raw commands (fast, precise for receipts/labels).
- Send HTML/CSS or images (slower; more flexible).
Example ESC/POS raw print for a receipt (text + cut):
”`js const config = qz.configs.create(“Your Printer Name”); const data = [ ‘’ + ‘@’, // Initialize printer