Overview

QZ Tray serves as an intermediary between the iVendNext web application and connected printers, enabling seamless direct printing from iVendNext POS without browser-imposed restrictions. This guide covers installation, configuration, and advanced management of QZ Tray to achieve reliable, silent printing for receipts, labels, and reports.

1. Understanding QZ Tray

1.1 Key Benefits

• Browser Agnostic: Works with Chrome, Edge, Safari (Firefox requires extra setup)

• Secure Printing: Certificate-based authentication prevents unauthorized access

• Advanced Features: Supports raw ESC/POS commands, PDF printing, and auto-retry

1.2 System Requirements

• Java 8+ (64-bit recommended)

• 2GB RAM minimum

• Admin rights for installation

2. Installation Process

2.1 Download & Setup

1. Download QZ Tray from https://qz.io

2. Run installer (keep default settings)

3. Launch application - appears as in system tray

Note: For enterprise deployments, use silent install flags:

qz-tray.exe --silent --autostart

2.2 Browser Configuration

3. Certificate Setup for Silent Printing

3.1 Generating Certificates

1. Log in at https://qz.io/login with Premium Support credentials

2. Navigate to QZ Tray > Certificate Generator

3. Complete CSR form with:

• Organization details

• 2048-bit key strength

• 2-year validity (default)

4. Download:

• digital-certificate.txt (public)

• private-key.pem (keep secure!)

Note: Currently, you cannot generate the certificate/keys in Safari. Other major browsers are all supported.

3.2 Installing Certificates

1. Place digital-certificate.txt in iVendNext's /public folder

2. Configure iVendNext to reference the certificate:

qz.security.setCertificatePromise(function(resolve) {

  resolve("/path/to/digital-certificate.txt");

});

Security Tip: Never expose private-key.pem to frontend code.

4. iVendNext Integration

4.1 Printer Configuration

1. In Hardware Profile:

• Set Printer Name to "QZ Tray"

• Enable Raw Mode for ESC/POS support

2. Test connection:

qz.printers.find("QZ Tray").then(console.log);

4.2 Print Format Adjustments

• Use 72mm width for best compatibility

• Avoid CSS floats (use tables for layout)

• Set margins ≥5mm to prevent clipping

5. Advanced Features

5.1 Automated Failover

qz.print({

  printer: 'Primary',

  altPrinters: ['Backup-Receipt'],

  data: [...]

});

5.2 Dynamic Content

Inject real-time data with:

data: [{

  type: 'raw',

  format: 'escpos',

  data: '1B 40 1D 57 80 31' // Open drawer command

}]

5.3 Batch Printing

Process multiple jobs sequentially:

qz.websocket.connect().then(() => {

  return Promise.all([printReceipt(), printLabel()]);

});

6. Maintenance & Troubleshooting

6.1 Certificate Renewal

1. Log in before expiration

2. Click Renew Certificate (preserves settings)

3. Replace only digital-certificate.txt

6.2 Common Issues

Here’s a quick look at some common issues you might run into.

6.3 Debugging

Enable verbose logging:

1. Right-click tray icon > Advanced > Logging

2. Reproduce issue

3. Share qz.log with support

7. Enterprise Deployment

7.1 Group Policy Controls

• Deploy MSI via Active Directory

• Lock settings with override.properties:

allow.unsigned.messages=false

allowed.addresses=192.168.1.*

7.2 High Availability Setup

• Install on print server with Always-On mode

• Configure load-balanced instances:

start qz-tray.exe --cluster=printers1,printers2