API Overrides

Compatibility

• ✅ 2.2 | ✅ 2.1 | ✅ 2.0 | ⛔ 1.9 | ...

Background

QZ Tray 2.1+ uses native promises and an internal sha256 hashing and require no additional dependencies.

QZ Tray 2.0 is bundled with RSVP to provide ECMAScript 6 Promise support. If RSVP is not desired, it can be overridden using qz.api.setPromiseType(...) to avoid ReferenceError: RSVP is not defined or Uncaught TypeError: Cannot read property 'promise' of null. Override examples are provided below.

Native Promises

1. Override RSVP with native Promises using qz.api.setPromiseType(...).

qz.api.setPromiseType(function promise(resolver) { return new Promise(resolver); });

BlueBird

1. Include the new promise library:

<script type="text/javascript" src="https://cdn.jsdelivr.net/bluebird/latest/bluebird.js"></script>

or via npm : npm install bluebird

2. Override RSVP with Bluebird using qz.api.setPromiseType(...).

// var Promise = require('bluebird');
qz.api.setPromiseType(function promise(resolver) { return new Promise(resolver); });

Q

1. Include the new promise library:

<script type="text/javascript" src="https://rawgit.com/kriskowal/q/v1/q.js"></script>

or via npm : npm install q

2. Override RSVP with Q using qz.api.setPromiseType(...).

var Q = require('q');
qz.api.setPromiseType(Q.Promise);

RSVP

Keep RSVP, but use it through a framework that doesn't pollute the global namespace:

var RSVP = require('rsvp');
qz.api.setPromiseType(function promise(resolver) { return new RSVP.Promise(resolver); });

WebSocket

As of Node 6.5, WebSockets are only available through 3rd party libraries causing Error: WebSocket not supported by this browser.

var WebSocket = require('ws'); // require('websocket').w3cwebsocket
qz.api.setWebSocketType(WebSocket);

Override SHA256

A hashing algorithm is required for signature validation. Use qz.api.setSha256Type(...) to override the default hashing library and avoid TypeError: _qz.tools.hash is not a function.

Native

Since QZ Tray 2.0.5, the native browser crypto can be used. This will only work with HTTPS pages.

Node 6.5

qz.api.setSha256Type(function(data) {
   return crypto.createHash('sha256').update(data).digest('hex');
});

• 2.0.1 and older only. Newer versions include this logic by default.

Node 4.5

• Requires sha.js

var createHash = require('sha.js');
qz.api.setSha256Type(function(data) {
    return createHash('sha256').update(data).digest('hex');
});

AngularJS

// qz-tray.js 2.1.0 and older
import * as sha256 from 'js-sha256';
qz.api.setSha256Type(function(data) { return sha256(data); });

// qz-tray.js 2.1.1 and higher: sha256 is bundled

Node Quickstart

Install dependencies:

npm install qz-tray ws q

Provide API overrides and start talking to QZ Tray:

var qz = require('qz-tray');
qz.api.setPromiseType(require('q').Promise);
qz.api.setWebSocketType(require('ws'));

qz.websocket.connect()
.then(qz.printers.getDefault)
.then(function(printer) {
   console.log("The default printer is: " + printer);
})
.then(qz.websocket.disconnect)
.then(function() {
   process.exit(0);
})
.catch(function(err) {
   console.error(err);
   process.exit(1);
});

AngularJS Quickstart

This is only for the API overrides. To set up signing, see assets/signing/sign-message.ts.

Install dependencies:

npm install qz-tray

Provide API overrides and start talking to QZ Tray:

import * as qz from 'qz-tray';

qz.websocket.connect()
 .then(qz.printers.getDefault)
 .then(printer => console.log("The default printer is: " + printer))
 .then(qz.websocket.disconnect)
 .catch(err => console.error(err));

Note, Angular 9 and higher will error with the following:

- ERROR in ./node_modules/qz-tray/qz-tray.js
- Module not found: Error: Can't resolve 'path' in 'node_modules/qz-tray'

Add the following entry to your package.json to omit path from AOT compilation:

"browser": { "path": false }

Note, Angular 11 and higher will error with the following:

- Could not find a declaration file for module 'qz-tray'. '/Users/owner/my-app/node_modules/qz-tray/qz-tray.js' implicitly has an 'any' type.

Add a file to src/qz-tray.d.ts with the following content:

declare module 'qz-tray';

QZ Tray 2.0

npm install js-sha256

import { sha256 } from 'js-sha256';                       // QZ Tray 2.0 and older

qz.api.setSha256Type(data => sha256(data));               // QZ Tray 2.0 and older
qz.api.setPromiseType(resolver => new Promise(resolver)); // QZ Tray 2.0 and older