1.9 QZ Print vs QZ Tray

Compatibility

• ⛔ 2.x | ✅ 1.9 | ...

Background

Below you will find the five new functions as they appear in the sample.html that is provided with the QZ Tray software.

• Information on how to use our Premium Support portal to generate the intermediate certificate and public/private keys can be found here.
• A detailed guide on how to sign messages to achieve silent printing can be found here.

Caveats

Below are unavoidable caveats introduced with adding a websocket wrapper. These caveats only exist in the 1.9 branch.

• qz.setPrinter(index) is not synchronous. Immediate calls to qz.getPrinter() will return undefined. Please make the necessary adjustments to accommodate, such as setting the printer name manually.
• Multiple qz.append() calls can cause performance issues. See Multiple Appends below.

New Functions

Function	Mandatory?	Purpose
getCertificate()	✅	Gets public certificate to display trusted message on load of page
signRequest()	✅	Calls a custom server-side signing function. See usage below.
qzSocketError(event)		Contains the event fired when the websocket encounters an error
qzSocketClose(event)		Contains the event fired when the websocket closes
qzNoConnection()		Calls function to fall back on QZ Print (applet version) if QZ Tray is not running

##qz-websocket.js

1. There's a new script, qz-websocket.js used for communication between the JavaScript API and the desktop application.

<script type="text/javascript" src="js/qz-websocket.js"></script>

1. The function deployQZ is still used, but has been re-purposed to deploy a WebSocket wrapper object.
2. To deploy the qz object using WebSockets, call deployQZ directly

deployQZ();   // sets up the global "qz" object, calls qzReady() when finished

Note: For backward compatibility with mixed environments, we have provided a fallback function deployQZApplet. This is not required for QZ Tray and is offered as a fallback mechanism for customers still using the NPAPI method.

getCertificate

The certificate can be provided through an $.ajax function, or can be pasted directly into the page (this is a public certificate). The certificate is only for the initial load.

1. AJAX method

   function getCertificate(callback) {
       $.ajax({
          method: 'GET',
          url: 'assets/auth/public-key.txt',
          async: false,
          success: callback // Data returned from ajax call should be the site certificate
   });

2. Non-AJAX method

Below is just a small sample of a what the public and intermediate key would look like.

function getCertificate(callback) {
    callback("-----BEGIN CERTIFICATE-----\n" +
        "MIIFAzCCAuugAwIBAgICEAIwDQYJKoZIhvcNAQEFBQAwgZgxCzAJBgNVBAYTAlVT\n" +

signRequest

1. This function is responsible for calling a custom script that performs the server-side signing. The signing can be done in a variety of different languages. Several examples are provided with the software in QZ Tray\demo\assets\signing. You can also click here for a growing list of examples including these languages: Ruby, Python, JavaScript, C#, J#, Java, ASP and VB.NET

   function signRequest(toSign, callback) {
       $.ajax({
           method: 'GET',
           url: '/secure/url/for/sign-message.php?request=' + toSign,
           async: false,
           success: callback // Data returned from ajax call should be the signature

});

***

### qzSocketError

 ```js
 function qzSocketError(event) {
     document.getElementById("qz-status").style.background = "#F5A9A9";
     console.log('Error:');
     console.log(event);

     alert("Connection had an error:\n"+ event.reason);
 }

---

qzSocketClose

function qzSocketClose(event) {
    document.getElementById("qz-status").style.background = "#A0A0A0";
    console.log('Close:');
    console.log(event);

    alert("Connection was closed:\n"+ event.reason);
}

---

qzNoConnection

function qzNoConnection() {
    alert("Unable to connect to QZ, is it running?");

    //run deploy applet After page load
    var content = '';
    var oldWrite = document.write;
    document.write = function(text) {
        content += text;
    };
    deployQZApplet();

    var newElem = document.createElement('del');
    newElem.innerHTML = content;

    document.write = oldWrite;
    document.body.appendChild(newElem);
}

Multiple Appends

QZ Tray 1.9 uses a WebSocket wrapper to simulate LiveConnect calls. This makes the API similar to QZ Print, however has the unintended side-effect of adding considerable latency to multiple calls to qz.append(...). This caveat only exists in the 1.9 branch. 2.0 uses a data object/array for appending and does not suffer this problem.

Making appends faster for QZ Tray 1.9

# Old QZ Print Syntax
- qz.append("foo\n");
- qz.append("bar\n");

# New QZ Tray Syntax
+ var data = "";
+ data += "foo\n";
+ data += "bar\n";
+ qz.append(data);