API: Print to AirPrint Printer

Allows you to trigger print requests to an AirPrint-enabled printer.

Requirements

  • Integration of our JavaScript API into your webpage
    • Sample code to run within the app and download for integration into your own project is available here.
    • Best practices for working with the JavaScript API are available here.
  • App Settings
    • Content > JavaScript API > Access JavaScript API = By Import
    • AirPrint > Enable AirPrint = On
  • Physical Hardware
    • AirPrint-enabled printer. iOS/iPadOS device must be on the same WiFi network as the printer. For more information about Airprint-enabled printers currently available and how to set up AirPrint, click here.


Triggers via API Functions

Check if AirPrint is Enabled

Supported in:

Kiosk Pro Basic, Plus and Enterprise

This function determines whether printing to AirPrint printers is enabled in Kiosk Pro's settings.

Format
kp_AirPrinter_requestStateOfSupporting();
		
Triggers

Following this call, Kiosk Pro will immediately trigger kp_AirPrinter_stateOfSupportingDidChange with the current state.


Check the Status of the Selected Printer

Supported in:

Kiosk Pro Enterprise

This function determines the connection status of the AirPrint printer Kiosk Pro is connected to in Automatic Kiosk Print Mode.

Format
kp_AirPrinter_checkStatusOfSelectedPrinter(callback);
		
Parameters callback - [string] the name of the callback to be triggered after the function has been executed
Callback Format
callback(statusCode)
		
Callback Return Values
  • statusCode - [integer] indicating the status of the printer. Possible values are:
    • 0 - AirPrint is disabled in Kiosk Pro settings
    • 1 - Print Mode is set to 'Standard Dialog'
    • 2 - no printer is selected
    • 3 - Selected printer is not available
    • 4 - Selected printer is available


Print Current Page

Supported in:

Kiosk Pro Basic, Plus and Enterprise

This function initiates printing of the current webpage or document.

Format
kp_AirPrinter_print();
		
Triggers

If the visitor cancels printing or an error is returned by the printer, the app will call kp_AirPrinter_printDidFailWithError with the appropriate error code.

If no error is returned by the printer, the job is assumed to be a success and the app will call kp_AirPrinter_printDidFinish.


Print PDF

Supported in:

Kiosk Pro Basic, Plus and Enterprise

This function initiates printing of the referenced PDF file.

Format
kp_AirPrinter_printPdf(filename);
		
Parameters filename - Kiosk Pro can print local or remote .pdf files using the following formats:
  • short filename (e.g. 'p1.pdf'). If no path is specified, Kiosk Pro will search for the file directly inside Kiosk Pro's Documents folder
  • relative path from Kiosk Pro's Documents folder (e.g. 'MyPDFs/p2.pdf')
  • full URL path to the remote PDF file (e.g. 'https://www.example.com/p2.pdf')
Triggers

If the file can't be found or is not available, then the app will call kp_AirPrinter_openPdfDidFailWithError with the appropriate error code.

If the visitor cancels printing or an error occurs during printing, the app will call kp_AirPrinter_printDidFailWithError with the appropriate error code.

If no error is returned by the printer, the job is assumed to be a success and Kiosk Pro will call kp_AirPrinter_printDidFinish.


Print HTML String

Supported in:

Kiosk Pro Basic, Plus and Enterprise

This function initiates printing of an HTML string.

Format
kp_AirPrinter_printHTMLString(string);
		
Parameters string - the HTML string to be rendered and printed
Triggers

If the visitor cancels printing or an error is returned by the printer, the app will call kp_AirPrinter_printDidFailWithError with the appropriate error code.

If no error is returned by the printer, the job is assumed to be a success and the app will call kp_AirPrinter_printDidFinish.


Notifications via API Callbacks

When Print Job Completes

Supported in:

Kiosk Pro Basic, Plus and Enterprise

This callback is triggered when a print job is sent to a connected AirPrinter and no error is returned.

Format
kp_AirPrinter_printDidFinish();
		

Note

This callback may be triggered without actually printing if a job is accepted and stored in the printer's print queue without returning an error to the app. For example, the Brother AirPrint printer we use for internal testing will accept print jobs even if it is out of paper and save them until new paper is added, at which point it will move ahead with printing automatically. As this may vary depending on the printer manufacturer, testing may be required with your specific printer set-up to determine how these types of errors are handled.


When Print Job Fails

Supported in:

Kiosk Pro Basic, Plus and Enterprise

This callback is triggered when visitor cancels printing or an error has occurred.

Format
kp_AirPrinter_printDidFailWithErrorEx(error);
		
Format error - [object] the error returned when printing fails. Includes the following:
  • domain - [string] where the error occurred
  • code - [integer] the error code
  • userDescription - [string] a description of the error
  • failureReason - [string] the reason the error occurred
  • recoverySuggestion - [string] how to resolve the error
  • debugDescription - [string] a detailed description of the error

Note

If the printer cannot print, but still accepts the print job successfully, no error is returned. For example, the Brother Airprint printer we use for internal testing will accept print jobs even if it is out of paper and save them until new paper is added, at which point it will move ahead with printing automatically; in this case, no error is returned by the printer and so we are unable to trigger this callback. As this may vary depending on the printer manufacturer, testing may be required with your specific printer set-up to determine when an error callback can be returned.


When PDF To Be Printed Cannot Be Opened

Supported in:

Kiosk Pro Basic, Plus and Enterprise

This callback is triggered when the PDF file named in kp_AirPrinter_printPdf cannot be successfully opened.

Format
kp_AirPrinter_openPdfDidFailWithError(errDescription, errDomain, errCode);
		
Return values
  • errDescription - [string] the localized description of the error
  • errDomain - [string] the receiver’s error domain
  • errCode - [integer] the error code

Errors are returned directly from Apple's Foundation framework. For more information on specific error codes that can be returned, click here.


When Enable State Changes

Supported in:

Kiosk Pro Basic, Plus and Enterprise

This callback is triggered when your code calls kp_AirPrinter_requestStateOfSupporting and each time the app is launched or an administrative user changes Kiosk Pro's settings.

Format
kp_AirPrinter_stateOfSupportingDidChange(supported);
		
Return values supported - [boolean integer] representing the current state:
  • 1 - AirPrint is enabled in Kiosk Pro's settings
  • 0 - AirPrint is disabled in Kiosk Pro's settings


Deprecated: When Print Job Fails

Replaced in 10.0 version with kp_AirPrinter_printDidFailWithErrorEx.

Supported in:

Kiosk Pro Basic, Plus and Enterprise

This callback is triggered when visitor cancels printing or an error has occurred.

Format
kp_AirPrinter_printDidFailWithError(errorCode);
		
Format errorCode = the code of the error as an integer. The following are possible:
  • -1001 - AirPrint is disabled in Kiosk Pro's settings
  • -1000 - AirPrint dialog is already showing
  • -999 - WebView failed to create the necessary printer controller
  • -998 - printing was not completed: visitor cancelled printing or another error communicated by the printer
  • -997 - Number of Copies setting <= 0
  • 1 - the device does not support printing
  • 2 - no print formatter, page renderer, printing item or printing items was assigned for printing
  • 3 - an image is in a format not recognized by UIKit for printing
  • 4 - an internal error occurred with the print job


Sample Code

  • This sample code relies on the JavaScript APIs built into Kiosk Pro and will not run successfully in other browsers or within our in-app help interface.
  • To run sample code, set the app's homepage to kioskgroup.com/airprint-api
  • To download a .zip of sample code, click here.

Change Log

  • Added in version 1.0. Ability to check the status of the selected printer added to Enterprise in version 7.9. Ability to print an HTML string added in version 10.0

Still stuck? How can we help? How can we help?