How It Works

How It Works

HP JetAdvantage Link for Web lets you run a browser-based web app on an HP printer, where users will launch and use your app right from the device's control panel. Your app will use the Link for Web libraries to utilize the scanning and printing functions of the device.

And since it's a true browser environment, you will develop your app using all of the same tools and technologies you already use to develop desktop and mobile web apps.

This page covers the following topics:

 

The Link Embedded Browser

The Link Embedded Browser uses a fully functional web browser engine that is optimized for embedded use and is supported by a wide range of devices and platforms, both embedded and desktop.

The Embedded Browser supports the following features:

  • JavaScript, AJAX
  • HTML4 (some HTML5)
  • XHTML1.0
  • CSS3
  • DOM2
  • Cookies (see note below)
  • Local storage
  • Animated GIF, GIF, BMP, JPEG, and PNG (sizes < 1,920,000 pixels)
  • GIF and PNG transparency
  • JavaScript trace logging
  • The following MIME types (MIME types not listed generate an error dialog):
    • image/bmp, image/gif, image/jpeg, image/png
    • text/css, text/html, text/plain, text/xml
    • application/javascript, application/x-javascript, application/xhtml+xml

The Embedded Browser does not support the following features:

  • All HTML5
  • History (history.go, history.back, and history.forward)
  • Pop-ups (for example, window.open() does nothing)
  • JavaScript remote debugging
  • Plugins (for example, video/flash)
  • Scalable vector graphics
  • GIF and PNG alpha blending
  • GIF and PNG opacity
  • XPATH
  • WML
  • File input type (for example, <input type='file' name='myFile'>) does nothing when clicked)
  • 'Save As' to local disk (for example, received content with an HTTP header of the form 'Content-Disposition: attachment; filename=myFile.xyz' is ignored)

Embedded Browser Cache

The Embedded Browser maintains a RAM-based cache to help reduce network traffic, server load, and perceived lag. The cache is cleared only when the device is power cycled.

The main resource (for example, an HTML document) associated with each web page is never cached by the device. Subordinate resources (resources referenced by the main resource, including: images, JavaScript, css files) are cached and the cached versions are used unless instructed otherwise by the web server through standard HTTP headers on the subordinate resources. For example:

 

Cache‑Control: no‑store The browser does not cache the resource. Hint: Configure the web server to use this header during development of your Web App to avoid the need to reboot the device to clear the cache.
Cache‑Control: no‑cache The browser submits the request to the web server for validation before using a cached copy of the resource.
Expires: <HTTP‑date> The browser caches the resource and use the cached version until the specified date/time.

 

Note: Apps must also take web-proxy caching into consideration if the resources are being accessed through a web-proxy.

Embedded Browser Appearance

When a user runs a Web App on a device (by pressing the App's button on the device's home screen), the device displays a screen containing a header, a browser panel, and in some cases, a footer. For example:


The layout of these elements can change from device model to device model (due to differences in screen sizes and look-and-feel), but with the exception of differences in browser panel sizes, the Embedded Browser provides consistent behavior and features on all device models.

Note that the Embedded Browser does not include some features commonly found on desktop browsers, including an address bar and navigation (forward/back) buttons. This is because the Embedded Browser is not intended for general-purpose web browsing. It is intended only to run Web Apps specifically designed for web-enabled devices.

Soft/Hard Home Buttons

A Home Button returns the user to the home screen. A "soft home button" is displayed on the touch screen. Some devices may also have a physical or "hard home button" somewhere on the display's frame.

When pressed, the Home Button may generate one or more key events (even if disabled). The generated event keyCode value(s) may vary from device to device, and so your Web App must not attempt to override/augment the default behavior by handling any key events associated with them.

The Web app can control the visibility (of the soft home button) and enablement of this button using the Link Environment.

Note: Unless there is a specific reason to prohibit the user from exiting the Web App, the Web App should always show and enable the Home button to give users an easy way to exit back to the home screen.

The Web App can also force a return to the home screen by using the JavaScript method window.close().

Start Button

The behavior of the Start Button is defined by your Web App. When pressed, the Start button generates an onKeyDown event with keyCode 113 (F2).

Your Web App can control the visibility and enablement of this button using the Link Environment.

Cancel Button

The Cancel Button is displayed any time there is an active job on the device which could be canceled. The Web App has no control or interaction with this button.

When pressed, the Cancel Button may generate one or more key events (even if disabled). The generated event keyCode value(s) may vary from device to device, and so your Web App must not attempt to override/augment the default behavior by handling any key events associated with them.

Title Panel

When your Web App is active, the content of the Title Panel reflects the TITLE element specified in the HTML header of the web page that is currently loaded. While the page is being loaded, or if the HTML header TITLE element is omitted, the title panel displays the title that was assigned to the corresponding button used to launch your Web App.

The title can be changed through JavaScript after the page has loaded using the JavaScript property document.title.

Alert/Error Button

The Alert/Error Button is displayed any time there is an issue present on the device which requires user intervention. Your Web App has no control or interaction with this button.

When pressed, the Alert/Error Button may generate one or more key events (even if disabled). The generated event keyCode value(s) may vary from device to device, and so your Web App must not attempt to override/augment the default behavior by handling any key events associated with them.

Help Button

The behavior of the Help Button is defined by your Web App. When pressed, the Help button generates an onKeyDown event with keyCode 112 (F1).

The Web App can control the visibility and enablement of this button using the Link Environment.

Browser Panel

The Browser Panel (highlighted in yellow in the image above) is where the Web App's pages are displayed.

Depending on the device's physical screen size and look and feel, the Browser Panel's height and width may change. Web Apps use standard JavaScript methods to determine the Browser Panel's width and height (as well as screen attributes):

var browserPanelWidth  = window.innerWidth;
var browserPanelHeight = window.innerHeight;
var screenColorDepth   = window.screen.colorDepth;

Scroll Bars

When scrollbars are allowed, they are displayed while scrolling and fade out of view after scrolling finishes.

Scrollbars do not take away from the client area are but instead are overlaid on top of the content area.

Soft Keyboard

When a user presses INPUT fields, a built-in Soft Keyboard will display so the user can enter/modify the text.

You may want your Web App to provide its own JavaScript-based soft keyboard or Input Method Editor (IME) to support auto-completion, PIN entry, or other features. If so, it can turn off the built-in Soft Keyboard using the Link Environment.

UI Timeout

The device maintains a UI Inactivity Timer.

Should the user launch a Web App and then leave the device idle longer than the UI Inactivity Timer setting, the device will automatically reset and return to the home screen. The UI Timeout duration setting can be configured using the device's Control Panel, EWS, or using WJA.

If the Web App requires extra time to complete a background task, the Web App may inspect the current UI Inactivity Timer setting and refresh the UI inactivity Timer using the Link Environment. Web Apps must be careful not to override the UI Inactivity Timeout forever.

Note that a Web App cannot modify the UI Inactivity Timer setting.

JavaScript Execution Duration Timeout

The Embedded Browser's JavaScript engine runs on the same thread as the device's UI. To keep a Web App from 'freezing' the device's UI for an unacceptable length of time, the Embedded Browser limits the duration of JavaScript execution to a maximum of ten seconds.

 

linkbase - Initializing the Link Environment

The Link Environment must be initialized before using any of the other Link for Web libraries.

When the linkbase library is initialized, a LinkEnvironment property will be attached to the window object. The Link Environment provides a set of properties and methods to control the behavior of the Embedded Browser.

The Link Environment has the following properties:

Name Type Description Default
deviceId string Globally unique device identifier (Example: 3e39cbdc-8760-4dd2-b598-a2898c35e702). No two devices will have the same ID. (Readonly) Factory Setting
deviceSerialNumber string The serial number assigned to the device at the time of manufacture. (Readonly) Factory Setting
deviceTargetName string The hostname/IP Address of the target device. "localhost" when running on a device/simulator, otherwise the supplied hostname/ipAddress of the target device being used for a remote debugging session. (Readonly) "localhost" or the value of the optional linkbase initialization parameter deviceTargetName
firmwareVersion string Current firmware version. (Readonly) Device Configuration
formatterSerialNumber string Serial number of the device's formatter (controller board). (Readonly) Factory Setting
helpButtonEnabled boolean Enables/disables the Help Button. If the device has a hard help button, this also enables/disables the hard button. When disabled, associated onkeydown events will not be generated. false
helpButtonVisible boolean Shows/hides the Help Button. false
homeButtonEnabled boolean Enables/disables the Home Button (including changing the appearance of the Soft Home Button, if it is visible). If the device has a hard home button, this also enables/disables the hard button. true
homeButtonVisible boolean Shows/hides the Soft Home Button. Has no effect on the behavior of the Hard Home Button. false
hostName string Fully qualified host name. (Readonly) Device Configuration
ipAddress string IP Address. When a device has multiple IP addresses, only one address will be provided. An IPv4 address (Example: '1.2.3.4') will be represented in IPv6 format (Example: '::ffff:1.2.3.4'). (Readonly) Device Configuration
macAddress string Mac address (will be of the form AA:BB:CC:DD:EE:FF). When a device has multiple MAC addresses, only one address will be provided. (Readonly) Factory Setting
modelName string Model name of the device (Example: 'HP LaserJet 500 color MFP M575'). Depending on the device and its options, it is possible to have two different devices with the same model name but different product numbers. (Readonly) Factory Setting
productNumber string Product number of the product (more specific than model name), represented typically in the form 'CXXXXA'. (Readonly) Factory Setting
softKeyboardEnabled boolean Enables/disables the embedded soft keyboard. true
startButtonEnabled boolean Enables/disables the Start Button. If the device has a hard start button, this also enables/disables the hard button and turns the hard button's LED green/red. When disabled, associated onkeydown events will not be generated. false
startButtonVisible boolean Shows/hides the Start Button. false
UIContextId string A device UI Context begins when an Link-based Web App is invoked and ends when the App exits/closes. The device generates a unique UIContextId (a cryptographic nonce string value) for every UI Context. Any Link Service method that reserves or consumes device functionality (scanning, priority mode printing, etc.) for exclusive use by the walkup user requires a valid uiContextId to be passed as a parameter. (Readonly) Generated by the Device Each time the App is Launched
uiInactivityTimeoutPeriod integer Number of seconds of UI inactivity after which the device will automatically return to the home screen. (Readonly) Device Configuration

 

The LinkEnvironment has the following methods:

Name Returns Parameters Description
emitTouchSound void none Causes the control panel to emit the sound made when a user touches an input element on the touch screen.
resetUIInactivityTimer void none Resets the device's UI Inactivity Timer. Solutions must not override the UI inactivity timeout indefinitely.

 

Example:

<script src="http://code.jquery.com/jquery-1.11.0.min.js"></script>
<script src="http://jalinkweb.hpdeveloper.com/linkbase-1.0.0.min.js"></script>

.
.
.

function Initialize(){
	linkbase.Initialize().then(
		function(){
			window.LinkEnvironment.homeButtonVisible = true;
			window.LinkEnvironment.homeButtonEnabled = true;
		},
		function(err){
			// Some error occurred
			// Check content of err
		}
	);
}


 

 

linkscan - Add Scanning to Your App

Once the Link Environment is initialized, you can then add scanning to your app.

The linkscan library provides a great deal of control over scan settings, destinations, metadata, user experience, and job status (see the API documentation). But in its simplest form, scanning can be added to an app in just 3 steps:

Step 1: Add the linkscan library


<script src="http://jalinkweb.hpdeveloper.com/linkscan-1.0.0.min.js"></script>

Step 2: Construct a minimal scan ticket using the device's defaults


// For simplicity, assume the device supports Job TransmissionMode, and Color PDF
$.when(linkscan.GetDefaultBasicOptions(linkscan.TransmissionMode.Job),
	linkscan.GetDefaultFileOptions(linkscan.FileType.Pdf, linkscan.ColorMode.Color)).then(
	function(defaultBasicOptions, defaultFileOptions){
		scanTicket.basicOptions = defaultBasicOptions;
		scanTicket.fileOptions = defaultFileOptions;
		
		scanTicket.destination = {
			uri: 'http://' + serverName + ':3001/scanreceiver',
			connectionTimeout: 60,
			responseTimeout: 120,
			maxConsecutiveRetries: 1,
			retryInterval: 60
		};
		scanTicket.scanFileNameBase = 'scan';
		scanTicket.transmissionMode = linkscan.TransmissionMode.Job;
	}
);

Step 3: Start a scan job


linkscan.StartScanJob(scanTicket);

 

linkprint - Add Printing to Your App

Once the Link Environment is initialized, you can then add printing to your app.

The linkprint library provides a great deal of control over print settings, job status, and user experience (see the API documentation). But in its simplest form, printing can be added to an app in just 3 steps:

Step 1: Add the linkprint library


<script src="http://jalinkweb.hpdeveloper.com/linkprint-1.0.0.min.js"></script>

Step 2: Construct a minimal print ticket (using a print-ready file from the web)


	var printTicket = {
		documentUri: 'http://' + serverName + ':3002/PrintFiles/Sample1.pdf'
	};

Step 3: Start a print job


linkprint.PrintUri(printTicket);

 

Installing and Running Your App

Any app intended for use on any HP device must be specially packaged (HPK file), submitted to HP for verification and validation (VAV), and finally signed by HP before it can be installed on a customer's device. The SDK contains an HPK Tool (HPKToolForWeb) to make it easy to package your app in an HPK.

Since your app is a web app, it isn't actually installed on the device. Instead, a Home Screen button representing your app is packaged in the HPK and installed on the device. The button definition includes:

  • Icon
  • Title
  • Description
  • URL (the location of your web app)
  • UUID

Check the list of Compatible Devices to make sure your device supports JA Link for Web.

Use the HPKTool to create your button definition and package it in an HPK file, as follows:

1. Enter or generate a GUID for your app (This GUID will uniquely identify this app on all devices where it is installed.)
2. Enter basic packaging information
3. Import Home Screen icons for your app from your local disk
4. Enter information the device will use to display the icon and launch the app
5. Save the HPK file to your local disk

 

When used with a device where the Link Debug Bridge (LDB) is enabled, the HPK tool will allow you to install your unsigned HPK so you can test out the installation process and your app's functionality before submitting your HPK to HP for VAV. Instructions for enabling LDB can be found in the JA Link Platform page here.

Follow these steps to install your HPK using the HPK Tool:

1. Under the Actions menu, select Install/Uninstall .hpk
2. Select your HPK file from your local disk
3. Enter the IP Address/Hostname (and EWS Admin password, if set) for the device
4. Click Install

 

As described on the Link Platform page, The HPK Tool can also be used to install your app's button on Link for Web compatible devices where the JA Link Platform and LDB are not enabled. In this case, the HPK tool will use an older, less secure protocol to install the button. When the Link Platform is not found on the target device, The HPK Tool will display a warning before installing the button:

 

 

Once installed, a button will be created on the device's control panel. (Note: You may need to press Reset on the control panel before the button will appear.) You can then launch your app by touching the button on the device's control panel.