API Overrides

Compatibility

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

Background

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.

QZ Tray 2.1 will use native promises and an internal sha256 hashing and require no additional dependencies.

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