Browser Print

Communicate with local Zebra devices over USB, Network, and Bluetooth from a browser with an easy to use JavaScript API.

Browser Print enables a website or web application to seamlessly communicate with locally connected devices on any supported platform. A single cross-platform JavaScript API abstracts away native intricacies and allows your team to focus on your product.

Installation

Browser Print requires a native application and a JavaScript library to function. The JavaScript library communicates with the native client application, and the native client application communicates with the devices.

Native Client Application

Download and install a native application here

Applications are available and supported on the following platforms:

  • Windows 7 or later
  • MacOS Yosemite or later
  • Android 7.0 or later

Applications are available by request for Ubuntu 16.4 or later. Please contact a Zebra sales engineer for access to the linux version of the application.

JavaScript Library

Include the base Browser Print library in your web page

<script type="text/javascript" src="BrowserPrint-3.0.216.min.js"></script>

Optionally, include the Zebra library. This library provides a higher level API on top of the base library that simplifies communicating with printers. The Zebra library requires including the base library to function.

<script type="text/javascript" src="BrowserPrint-Zebra-1.0.216.min.js"></script>

The JavaScript libraries are supported on the following Browsers:

  • FireFox 66 or later
  • Google Chrome 51 or later
  • Internet Explorer 11
  • Safari*

*These browsers do not support http connections to the loopback address from a web page delivered over https. Using these browsers requires the end user to accept a self-signed certificate.

Getting Started

Finding Devices

Discover all of the devices that are available to the host system:

BrowserPrint.getLocalDevices(function(deviceList){...});

The success callback will be called when device discovery has completed, and it will be passed a list of devices as BrowserPrint.Device objects.

Discoverying devices can be quite time consuming when the client has enabled network and/or bluetooth discovery. Browser Print provides a mechanism for the user to set a default device to avoid having to run a full discovery on every page load. Each category of device can have a single default set. The following code retrieves the default printer:

BrowserPrint.getDefaultDevice("printer", function(device){...}, function(error){...});

If the end user has set a default device for the specified type, the success callback will be called and passed the default device as a BrowserPrint.Device. If no default device has been set, null will be passed to the callback. It should be noted that there is no guarantee the default device is online, since it is returned statically without any connection attempts by the client.

Communication

Once a BrowserPrint.Device object is obtained, several methods are available to facilitate communicating with the device. The following examples assume the selected device is a Zebra printer set to use the ZPL language.

Writing

The following command will print a configuration label:

device.send("~wc", function(success){console.log("Sent to printer");}, function(error){console.error("Error:" + error);});
Reading

Bi-directional communication is supported. The following code shows how to send a request to the printer for it's configuration, and then reading the response back:

device.send("^XA^HH^XZ", function(success){
    device.read(function(response){
       console.log(response); 
    }, function(error){console.error(error);});
}, function(error){console.error(error);});
Resource Conversion

Browser Print supports converting resources to different formats. This is usually used to convert image files into printable formats, but other conversions may also be supported. The format conversions supported will depend on the client application version.

BrowserPrint.convert("https://example.com/myimage.png", device, options, success, failure);

The behavior of BrowserPrint.convert will depend strongly on the options provided. Through the options, the application can control how the resource is manipulated, such as resizing or dithering. The options also control how the output is handled, such as sending the converted resource directly to the device or returning the result to the browser.

Zebra Library

The Zebra Library is built on top of the base library by wrapping BrowserPrint.Device to provide an enhanced interface for easier integration and communication with Zebra devices.

Features include communication queueing, parsing device responses, and automatically determining resource conversion options based on device configuration.

WARNING: Creating a Zebra.Printer object initiates communication with the specified device.

Create a Zebra.Printer device by passing a BrowserPrint.Device

var zebraPrinter = new Zebra.Printer(device);

Creating a Zebra.Printer object automatically queries the printer for its current configuration. This helps speed up other calls that require the printer configuration information to function correctly. Any call to getConfiguration will update the saved configuration stored in the Zebra.Printer object.

Query The Printer

The library provides convenience methods for many common printer queries. These functions will query the printer for the information, and parse the responses into easy to use objects.

Request the printer's status:

zebraPrinter.getStatus(function(status){console.log(status.getMessage());}, function(error){});

Get printer configuration (This is a convenience method for the previous ^HH example)

zebraPrinter.getConfiguration(function(response){}, function(error){})

Retrieve a SetGetDo(SGD) value:

zebraPrinter.getSGD("device.friendly_name", function(value){}, function(error){});

Get model and firmware information

zebraPrinter.getInfo(function(info){}, function(error){});

Queued Communication

JavaScript is asynchronous, but the printer is not. Sending multiple query commands to the printer in succession will most likely result in all of the responses being concatenated together into the response of the first read attempted

The Zebra.Printer object will manage sending the query commands, reading and parsing the responses, and calling the proper callback methods so that requests are handled one at a time.

For example, if the following code is run:

zebraPrinter.getStatus(function(status){}, function(error){});
zebraPrinter.getConfiguration(function(response){}, function(error){});
zebraPrinter.getSGD("device.friendly_name", function(value){}, function(error){});

Each request command will be sent to the printer, and the response to that command will be read and parsed before the next request is sent. Each request's callback function will only receive the device response for that request.

Resource Conversion

The Zebra Library provides serveral convenience method for resource conversion. These methods accept the resource as a URL, or as a blob

Printing an image as a label will automatically resize the image to best fit the label, based on the print width and label length:

zebraPrinter.printImageAsLabel(url, function(){}, function(error){});

Images can also be converted and returned to the browser for inclusion in a separate label being generated. This is also useful for images that are expected to be used often, as the conversion only needs to be done once.

zebraPrinter.getConvertedResource(url, options, function(imagaData){}, function(error){});

Images can also be stored to the printer to avoid sending the data with every use. The following will convert the provided resource and return the name of the file as it is stored on the printer.

zebraPrinter.storeConvertedResource(url, options, function(fileName){}, function(error){});

Promises

Most of the Zebra.Printer methods accept success and failure functions as callbacks for when the operation completes. However, if neither success or failure are supplied to the method call, the method will return a Promise.

The promise API makes it easier to chain multiple commands together. The following code checks if the printer is ready to print, and if it is, a configuration label is printed. If the printer is not ready, an error is thrown and handled in the catch function.

zebraPrinter.isPrinterReady().then(function(){
    return zebraPrinter.write("~wc");
}).catch(function(error){
    console.error(error);
})

Best Practices

These are general guidelines for using this library efficiently and successfully. The specific requirements of your application may not apply to all of these suggestions.

Client Installation

If you expect end users will access your web page without installing the native client prior to visiting, the page should detect failure to communicate with the native application and provide instructions to install it.

Client Compatibility

It is possible that a user will have a version of the native client application installed on their machine that is older or newer than the version your web page was developed for. The native client application will attempt to maintain backwards compatibility with older versions of the JavaScript library whenever possible, but it is the web application developer's responsibility to ensure their application only uses features available from the version of the user's installed client application.

Information about the native client application can be obtained by calling BrowserPrint.getApplicationConfiguration() This call will return information about the client, such as version, build_number, api_level, and the operating system platform.

The JavaScript documentation lists a "Client API Level" value for every function. This is the minimum Client API level required to use that function. If your web application requires functionality only available in a higher API Level, the application should check the user's native application API level and either request the user to upgrade their native application, or provide reduced functionality.

Device Management

On page load, your application should call both BrowserPrint.getDefaultDevice() and BrowserPrint.getLocalDevices(). The application should assume the user wants to use the default device, but provide the user the ability to change the device and select from the list of available devices. Calling both methods on page load makes device discovery appear faster to the user.

Printing

The application should confirm that the printer is ready to print before sending a print job to the printer. Calling the zebraDevice.isReadyToPrint() method before sending a job will tell the application if the printer is ready to receive print jobs. Calling the same zebraDevice.isReadyToPrint() method after sending a print job will inform your application if the printer has developed any errors since the last print job was sent. Any errors developed after a job is sent likely means the error occurred while printing the job, indicating the last job is not likely to have completed successfully. If the printer is not ready to print, calling zebraDevice.getStatus() will inform the application of the exact error.