QZ Setting
Introduction
QZ Tray is a desktop application that allows you to print labels, barcodes, receipts, and more directly from web pages using HTML, JavaScript, and Java. It's particularly useful for automating printing tasks and integrating printing functionality into web applications.
1. Steps to configure QZ Tray Application
The steps to configure QZ Tray Application are explained below:
Step 1. Navigate to Home > Retail. Then under the Hardware Setup section click on the QZ Setting shortcut.
This should take you to the QZ Setting screen.
Enter the Certificate Information.
Click the Save button to save the changes and exit the screen.
Installing QZ Tray Application
You need to download and install QZ Tray on your system. The application is supported in almost all browser types except Firefox. The Firefox browser is the only browser that requires any additional steps.
The screenshots may look different depending on your operating system and the version of QZ Tray you are running, but the steps in this article should be nearly identical.
The steps to install the QZ Tray application are listed below:
Step 1 - Install Java 7 or higher from Oracle's website.
Note: QZ Tray 2.1 and HTML printing require Java 8 or higher. See detailed system requirements.
Step 2 - Download the appropriate version of QZ Tray for your operating system
Step 3 - Install, taking the defaults.
Certificate Generation
You must generate a public certificate and a public/private key pair for signing messages.
Note: For renewals, please see certificate renewal steps instead.
The steps to generate a Certificate are explained below:
If you have purchased Premium Support, you can follow the steps below to generate a Certificate and Private Key pair to suppress dialogue warnings.
Navigate to https://qz.io/login/
Enter the primary email address and product key and click Sign In
Note: Make sure there are no blank spaces before or after the product key.
Once signed in, select QZ Tray.
At the next screen you have the ability to generate a CSR (Certificate Signing Request) and a public/private key pair.
You may already have a CSR and/or a public/private key pair. If that is the case, you can upload either of these at this screen. It must be 2048-bit. If you do not upload anything, a public key, private key, and a certificate will be generated.
Fill in the required fields and hit Submit request
Note: Currently, you cannot generate the certificate/keys in Safari. Other major browsers are all supported.
After a few seconds a new field will appear at the bottom of the page. Download the public key, private key, and certificate.
Download the appropriate private key format for your environment. Most environments require PEM, however .NET environments require PKCS#12 (PFX)
All three downloads will not be available if you provided QZ with a CSR or a public/private key pair. The digital certificate will always be provided by QZ.
This key chain will be used by QZ Tray to verify the authenticity of signed messages and to suppress the print warnings.
Encrypt Private Key: Optional. Note, encrypted keys will not work with JavaScript signing examples.
Private Key: private-key.pem PKCS#8, private-key.pfx PKCS#12; needed for signing messages. This allows silent printing.
Public Key: public-key.txt x509; Not needed for printing, but is used to request new certificates.
Digital Certificate (Trusted Certificate): digital-certificate.txt Used on page load for silent printing.
Important
For security reasons, it is advised to store your private key in a secure location. Your private key should never be given out to anybody. If your private key is leaked, someone with malicious intents will be able to sign traffic on your behalf.
If you believe your private key has been leaked, please let us know so we can blacklist this key.Note: The certificate and the private key are generated by YOUR web browser. This means we never get a copy of it, and could never pretend to be you while we print.
Now that you have these keys, navigate to the signing tutorial for instructions on how to securely sign messages.
License and Certificate Renewal
Please check the following points before you proceed with Certificate renewal.
Renewals only. For new orders, see generate certificate steps instead.
Any remaining days on your previous certificate will roll into the renewed certificate.
Renewal discounts are applied automatically. Contact support with any questions.
Multi-year discounts are applied automatically. Contact support with any questions.
Renew License
The steps to renew the License are as follows:
Navigate to https://buy.qz.io/myaccount.asp (alternatively, https://buy.qz.io and click "My Account" at the top of the screen)
Once signed in click "Buy Now" at the top of the screen.
Select ADD TO CART on the appropriate product (Premium Support -- or -- Company Branded + Premium Support)
Enter in the desired years you wish to purchase and select PROCEED TO CHECKOUT.Note: Price should be discounted for renewals, reach out to the QZ Support Team if a discount does not display.
IMPORTANT: Towards the bottom of the page, there will be a section to add in your current product key. After putting in your product key, along with all of the other required information, select CHECKOUT
You will be emailed and assigned a new product key. Any remaining days on your previous certificate will roll into the renewal.
Renew Certificate
The steps to renew the Certificate are as follows:
Log in here https://qz.io/login/ using your email and newly assigned product key
Select QZ Tray
If you do not need to change any of the information on the certificate from the previous year (e.g. Company Name), it is recommended to click the "Renew certificate" button at the top of the page. This is the recommended option, only digital-certificate.txt needs to be replaced on the server.
Alternatively, if you need to change the information, click "Show other options" and take the default settings.
Certificate Replacement
Please check the following points before you proceed with Certificate replacement.
Use the digital-certificate.txt on your website in place of the old copy(s)
The certificate is generally located in a public directory accessible by JavaScript $.ajax() or fetch().
Find and replace digital-certificate.txt on your web server.
If the contents of this file were instead pasted directly into code, search project for -----BEGIN CERTIFICATE-----.
Since QZ Tray 2.0.8, simply replacing digital-certificate.txt is all that is needed.
Replacing Certificate (Deprecated)
Websites that were integrated prior to QZ Tray 2.0.8 may need to manually clear the cache.
WARNING: The ?modify_url technique is available for historical purposes and discouraged. Instead, please use a cache flag for $.ajax(), fetch(), etc.
You can force a reload of the cache by modifying the URL. e.g.- http://foo/bar/digital-certificate.txt
+ http://foo/bar/digital-certificate.txt?modify_url
If the above URL is referenced from a JavaScript file, the script file may need to be force refreshed as well, e.g:
- <script src="foo/bar/myscript.js"></script>
+ <script src="foo/bar/myscript.js?modify_url"></script>
Certificate Verification
To ensure that the certificate has been replaced properly, you must visit a webpage which uses QZ Tray.
Visit a webpage which uses QZ Tray AND uses the recently deployed certificate.
Ensure QZ Tray is functioning properly by listing printers or doing a test print.
(You may also use serial, USB or file communication as a test.)
From the QZ Tray menu:
Click Advanced > Site Manager
Ensure the "Valid To" date is correctly updated
If the certificate was replaced properly there will be no warnings when printing. If you receive an Expired certificate or Invalid signature, please reach out to QZ Support Team immediately for assistance.
Private Key Replacement
Most renewals will re-use the old private-key.pem or private-key.pfx. These steps are provided ONLY in the event that the private-key.pem or private-key.pfx was replaced as part of the renewal process. Do NOT perform these steps unless you explicitly generated a new private key above.
If a new private-key.pem or private-key.pfx was generated above, replace this as well. This varies per-platform. Please contact a developer and place support@qz.io on a copy of communications.
The private key is generally located in a non-public directory, used by a signing mechanism. This is generally referenced in a file named sign-message.php or similar.
If the contents of the private key were instead pasted directly into code, search project for -----BEGIN PRIVATE KEY-----.
Questions, comments or concerns, please contact the QZ Support Team
